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PREFACE 



The Apple lies** 1 computer is the most powerful member of the Apple* II famil} 
of microcomputers. Not surprisingly, it is also the most complex and the most 
difficult to program. 

The purpose of this book is to show you how to develop software that takes 
advantage of I lie unique features of the cs without forcing you to silt through the 
thousands of pages of technical information available from Apple Computer, Inc. 
The major new features 1 will cover include the enhanced operating system 
(ProDOS' 8 16), a powerful sound system, two super high-resolution color graphics 
display modes, and hundreds of standard subroutines, called functions, a program 
can use to perform various operations. 

The GS operating system groups related software functions into data structures 
called tool sets. Two examples of tool sets are the Memory Manager (which controls 
memory usage) and the Event Manager {which deals with user input activity). The 
cs also has several tool sets you can use to develop programs that take advantage 
of the desktop environment popularized by the Macintosh™ computer: the main 
ones are QuickDraw II {for drawing on the graphics screen), the Menu Manager 

fur Implementing pull-dow ams). the Window Manager (for handling multiple 

windows on the graphics screen), and the Dialog Manager (lor handling user selec- 
tions! 

All the commonly-used tool sets are analyzed in this book For convenience, tool 
Set reference tables are included at the end of every chapter that reviews a tool set. 
For each function, these tables contain the function number and the list of param- 
eters the Function expects to receive when called 

The programming examples in this book were written in 658 1. 6 assembly Ian* 
guage. (There is a good reason for this: high-level language compilers for C, Pascal, 
and BASIC were not available when this book was written.) As a result, you will 
Find this book more valuable if you have assembly language experience. Even if you 
do not, however, the descriptions of what the tool set functions do and how they 
interact with one another will be useful, Converting assembly-langatige function 
calls to high-level langange commands should not be difficult. 

I give an overview of 65816 assembly language programming techniques in 
chapter 2. If you are a total stranger to assembly language programming, I suggest 
you first read a book totallv devoted to the topic. The best are 65816/65802 Assembly 
Umguage Programming by Michael Fischer and Programming the 65816 by David 
Eyes and Ron Lichty, 

As you will quickly discover while reading this book, the gs supports most of the 
hardware and software features of the Apple* He and lie computers. These features 



have been exhaustively covered in three of my earlier books. Inside the Apple lie. 
Inside the Apple He. and Apple PruDOS: Advanced Features for Programmers. The 
latter book describes what is now called the ProDOS® 8 operating system 



It would not have been possible to write a book like this so soon after the 
introduction of the cs without the technical support of Apple Computer, Inc. My 
thanks to all those at Apple who put up with my many telephone calls and electronic 
letters. Those who were particularly helpful were Rob Moore, Jim Merritt, and 

Steve Glass. 



Gary B. Little 

Vancouver, British Columbia. Canada 

June 1987 
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CHAPTER 1 



Exploring 
the Apple Hgs 



On September 15. 1986. Apple Computer, Int. revealed -In Vpple lies™ computer, 
the first new model in the Apple* 11 family since the Apple* lie (April, 1984) and 
the Apple* He (January, 1983) computers. The cs portion of the name stands for 
Graphics and Sound, the two exciting features of the GS that distinguish it From the 
He, He, and. in many ways, from most other microcomputers as well. 

Building the cs was nol an eas> task for Apple's engineers because of one critical 
design constraint: the GS, even with its fancy new sound, graphics, and processing 
capabilities, had to be able to run software originally developed for the lie and lie. 
Nevertheless, the project was successfully completed. The result is a computer that 
runs almost all software available lor the He or He but that ha.s enough unique new 
features to keep programmers and users satisfied for years to come. 

This chapter reviews tin important hardware features of the CS while highlighting 
the differences between the GS and the He and Ik: systems. Also provided is a 
cursory look at the new operating system software Apple provides with the GS, Once 
sou are familiar with the overall makeup of the GS» you will quickly recognize its 
potential from a programmer S point ol View, Subsequent chapters examine how to 
develop software for the GS that takes full advantage of its new features. 

MICROPROCESSOR 

The cs uses The Western Design Center W65C816 microprocessor, not the 65C02 
used in (lie lie and lie. The 65816. as it is more commonly known, is a versatile 
device that can operate in an B-bil emulation mode in which it mimics the operation 
of a 65CU2 almost exactly, or in a more powerful 16-bit native mode, (See Appendix 
2 for a technical description of the 65616.) 

The 65816's ability to emulate the 65C02 made it the obvious choice as the 
microprocessor for tin- cs, Without this ability to emulate, the GS would not be able 
to run lie and lie software unless a slow software interpreter or (heaven forbid i the 
65C02 were used. 



Another important factor in choosing the 65816 was that it also has enough 
horsepower to handle rigorous new programming chores, such as managing large 
amounts of memory and performing complex color graphics operations. In its native 
operating mode, the 65816 supports the following features; 16-bit registers, more 
instructions, more addressing modes, and a relocatable direct pas;, and stack. The 
65816 also has a 24-bit address bus. so it can directly address a 16-megabyte memory 
spar 

The 65816 operates at either 1.0 MHz (normal mode) or 2.8 MHz (fast mode) on 
the GS. The default mock' is the fast mode, in which programs run about two and 
one-hall limes faster than they do at normal speed. The 65C02 on the lie or lie 
runs at only 1.0 MHz, although jl is possible to purchase accelerator boards for the 
He to speed it up by a factor of three or more. 

MEMORY 

The address space for the 65816 is an enormous 16 megabytes and is directly 
addressable (thai is, every byte has a unique address). Contrast this with the 65C02, 
which has only a 64K address space; additional memory duplicates these addresses 
and can be accessed only using relatively complex bank-switching techniques. 

Chapter 4 takes a detailed look at how the GS makes use of the 16M address 
space. In brief, a standard GS has 256K of RAM. expandable to 8M. and 128K of 
ROM. expandable to IM. (It also has RAM to support the sound system and the 
Control Panel, but this memory is not part of the 65816 address space.) To add 
extra memory, you must insert a memory expansion card in a special peripheral slot 
OH the GS motherboard. 

Ol the 256K oi HAM. the first 128K is roughly equivalent to main and auxiliary 
memory on the He and He. The other 128K is needed to support the operating 
system, system monitor, device drivers, and special video display modes. 

The I28K ROM space on the GS contains a great many support programs and 

subroutines a programmer can use: 

• The same Applesoft® programming Language as in the lie and lie 

• A System Monitor similar to the one on the He and He but with several new 
commands 

• A Mint-Assembler like the one on the enhanced He and He. but extended to 
support alt 65816 instructions and addressing modes 

• System diagnostics 

• Built-in classic desk accessory programs: Control Panel (for setting the system 

configuration) and Alternate Display Mode dor allowing lie- and Hc-stvle 
programs to use page 2 of text) 

• Drivers for built-in input/output (I/O) de\ i 
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• A driver for the AppleTalk 8 network 

• Soft switches for configuring the system and performing I/O operations (these 

are actually memory-mapped 1.(1 locations) 

• Tool sets: Tool Locator, Memory Manager, Miscellaneous Tool Set, QuickDraw 
II, Sound Manager, Desk Manager, Floating-Point Numerics (SANE ' \, Apple 
DeskTop Bus™ Tool Set. Scheduler, Integer Math Tool Set, Text Tool S, t 
Event Manager, and RAM Disk Tool Set 



A tool set is made up of several subroutines (or functions), each performing the 
same general type of operation. The Memory Manager tool set, lor example, contains 
several functions for doing such chores as allocating blocks of memory, releasing 
blocks, calculating free space, and performing other memory-related operations. 
Most of this book deals with how to use tool set functions in your own programs, 



I/O INTERFACES 

From an I/O point of view, the cs combines the best features of the He with the 
best features of the He. Like the lie, the c;s contains seven general-purpose pe- 
ripheral expansion slots numbered from 1 to 7. As a result, almost any peripheral 
board originally designed for the He can be used with the GS as well The main 
exceptions are multifunction cards, such as the Street BusinessCard and the Pro- 
metheus Versacard, which simulate the efTect of having an I/O device in a particular 
slot even though the card plugs into a different slot, (These devices are said to use 
phantom slots.) 

The GS also has a unique eighth slot for memory expansion only. Through it you 
can add up to 8 megabytes of RAM memory as well as additional ROM memory. 
Although the standard Apple GS Memor> Expansion Card actually holds only 1M 
of RAM, other manufacturers sell cards with greater capacities. (See Appendix 6 for 
information on available CS memory expansion cards.) 

In addition to expansion slots, the CS has the same built-in expansion port* as 
the lie, plus a few more. Here are the ones that correspond to standard slot numbers: 



• Port 1: serial printer port 

• Port 2; serial modem port 

• Port 3: video port 

• Port 4; mouse port (part of the Apple DeskTop Bus™) 
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Photo 1-1: The Back Pane! of [lie Apple lies. Showing the I/O Connectors 




• Port 5 

• Port 6 

• Port 7 



disk -drive purl (SmartFort) 

544-inch disk -drive port 

AppleTalk (actually uses serial port 1 or 2) 



As shown in photo 1-1, the connectors for these ports are located on the back panel 
ill the gs, 

Hu other major I/O ports are two game control ports, a built-in clock/calendar, 
and a sound synthesizer. 

it is important to realize thai an internal port and its corresponding slot are 
mutually exclusive, In other words, you can use only one or the other. It is not 
possible to switch between an internal port and a plug-in card without turning the 
GS oil and then on again, 

To tell the cs whether you waul to use a slot or a port t you must use a built-in 
configuration program railed the Control Panel. It is an example of a Classic Desk 
Accessory (see chapter 9), a utility program you can switch to even when you are 
using another program. 



4 Exploring the Apple Has 



To bring up the classic desl< accessory menu, enter Controi-QpenApple-Esc from 
the keyboard. This pops up a list ol desk accessories you can use, beginning with 
the Control Panel. To activate the Control Panel, use the up- and down-arrow keys 
to move the inverse bar over its name, and then press Return. You will then see 
the main command menu for the Control Panel Must of these commands are for 
setting global parameters that configure the system the way you want, Fur example, 
there are command .-t the date and time, default video characteristics, and 

keyboard options. 

The Slots command is used to set the desired slot/port configuration. Once you 
select it. you will see a list ol slot numbers and an indication ol whether a built-in 
port or "Your Card" (a card in a slot) is to he active. The default set-up selects 
internal ports I through 6 and your card in slot T, If you wanted to use a parallel 
r card in slot I. you would use the right-arrow kc\ to change the entry lor 
slot 1 to "Your Card." The next time you start up the CS, the card in slot 1 will he 
used instead of serial port 1. 

The parameters set up by the Control Panel are stored in a memory area asso- 
ciated with the c:s clock chip :not part of the 65816 address space;- This memory 
area is nonvolatile (because it is powered by the clocks battery), so the GS remem- 
bers the Control Panel settings even when the CS is turned oil. 

RCA Mini Headphone Jack 

By plugging headphones into the RCA mini headphone jack, you can divert sound 
from the GS*S on-board speaker to the jack. Although it is a stereophonic jack, the 
GS sound circuitry sends the same output signal to both channels, so you will not 
hear true stereophonic sound unless you add an optional sound card. 

Serial Ports 

The GS lues two built-in serial interface ports driven by a Zilog S530 Serial Com- 
munications Controller (SCC), the same chip used on the Macintosh"' computer. 
By convention, the first port (port 1) should be used with a serial printer, such as 
the Image Writer® II. and the second (port 2) should be used with a modem, such 
as the Hayes Smartniodem. You can also use either port to connect the GS to an 
AppleTalk network; in tins case the serial port you choose behaves like a port 7 
device. 

The S530 i* not the same as the serial chip ased on the He and the Apple Super 
Serial Card, This means that programs for the lie or Super Serial Card that access 
serial hardware registers directly will not work on the c:.s without a new device 
driver. Most programs that are chip-Specific are communications programs. Printing 
programs do not usually cause problems, because output goes through the firmware 
that controls the serial port, at this level, the serial ports are largely compatible, 
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Game L/G Port 

The game I/O port is a nine-pin DB-9 connector used to interface game controllers 
such as joysticks, paddles, and push tuitions. It is equivalent to a similar port on 
the back oi the lie and He. With it you can measure the settings of tour variahle- 
resistanoe devices (such as two X-V joysticks) and three single-hit switch inputs. 

The motherboard of the GS also has a rectangular 16-pin game connector that is 
identical to the one on the He. It provides all the electrical signals of the game I/O 
port as well as lour single-bit output annunciator signals for driving indicator Eights 
or Simple reins s. 

Disk-drive Port 

The disk drive port is similar to the one on the hack of the He. It is an Apple 
Smart Port interlace, which means that you ran connect to it any device adhering to 
the SmartPort hardware and software specifications, tins includes 3V&-incli drives, 
such as the UniDisk™ 3.5 and the Apple 3 5 Drive, and 5/vineh drives, such as 
the Urn Disk 5.25 and the Duo Disk* 

To add disk drives to the GS, all you have to do is daisy-chain them to the 
SmartPort in the correct order. (See appendix 7 for information on available lies 
disk drives.) The Apple 3.5 Drives must be connected first (two maximum), followed 
In any number of UniDisk 3.5 drives, and then followed by any S^i-inch drives 
(two maximum; 1 . Because of power supply limitations, you should not add more than 
two UniDisk 3.5 drives to the chain. 

The <;s treats the 5'/i-ineh drives at the end of a SmartPort device chain as port 
6 devices, even though the disk-drive port is internal!) mapped to port 5. This 
means that you can hunt from the 5 1 vimh drive with an Applesoft PR#6 command, 
If you want to use your 5Vt-incli drives with a disk controller card in slot 6 instead, 
use the Control Panel Slots command to change the slut fi entry to "Your Card." 

The Control Panel also lets you choose which disk device yon want the t;s to 
boot from when you turn it on or when yon enter Control-OpenApple-Reset. The 
default is "Sean." which tells the CS to look lor a drive from slot 7 down to slot 1 
and to hoot from the first one it finds with a bootable disk. You can also specify a 
specific slot number to boot from; do this if you want to boot directly from the first 
3'/2-inch disk in port 5 instead of from a 5' i-inch disk in port 6. for example. 

Using the Control Panel RAM Disk command, you can also allocate an area of 
memory For use as a RAM disk device. RAM disk memory contains data that is 
formatted in the same way as on a real disk. Data is read or written using the same 
commands as tor a standard drive, hut I/O operations are much faster because there 
is no waiting for slow-moving mechanical parts. The main drawhack of a RAM disk 
is that data on the RAM disk disappears when you turn off the power, so you must 
transfer it to a real disk before turning oil tin- computer. 

II the RAVI disk lias been properly formatted with all the code necessary tot 
hooting, you may want to assign it as the hoot device instead of a real disk drive. If 
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you do so, the operating system will reload more quickly after a ( lontrol-OpenApple- 
Reset reboot. 

The GS also supports any ROM disk device you might have on a memory expan- 
sion card. A ROM disk, like a RAM disk, is fast, bul its contents arc permanent In 
a typical case, a ROM disk would contain the <;s opera! iog system and any utility 
or application programs to which you need instant access 

Analog RGB Video Port 

You can connect an analog RGB monitor, such as the AppleColor RGB Monitor, to 
the analog RGB video port to view the 4,096 colors the t;s supports in its super 
high-resolution graphic display mode. Yon cannot connect digital RGB monitors to 
this port. 

Composite Color Video Port 

The GS also generates an NTSC-cnmpatihle composite color video output signal 
The port connector is an RCA phono connector. You can use the VI S( signal to 
drive an ordinary monochrome monitor or a composite color monitor, 

Apple DeskTop Bus Port 

The Apple DeskTop Bus \DBl is a unique data transmission interface designed to 
allow you to connect, in a chain, certain types of input devices to the <;s. The two 
most common ADB de\ ices are the keyboard and the mouse, which come with tin- 
es. The ADB protocol is general enough, however, to work with other pointing 
devices, such as trackballs and joysticks. The GS communicates with any device on 
the ADB by sending it commands and listening for responses; communication signals 
can he directed to a particular device lo avoid interfering with other devices in the 
chain. 

Connected directly to the ADB is the keyboard. (See photo 1—2). Il contains SO 
keys, including a 14-key numeric keypad. The layout oi keys is almost the same as 
the layouts on the lie and Me keyboards, bul with one important difference: the 
Option key (formerly called the Solid-Apple key) is now on the left side of the space 
bar. Just to the left of the Open-Apple key. 

The main new feature of the keyboard is ils program main lily B\ changing Control 
Panel parameters, you can adjust the auto- repeat rate of the keys and the time delay 
before repeating begins. Von can even make the space liar. Delete key, and arrow 
keys repeat more quickly than other keys. Another niee feature is the ability to 
enable keyboard buffering allowing you to type ahead of your program. Finally, you 
can determine, Iroin a program, whether any key on the keyboard is down, even 
modifier keys like Shift, Control, and Caps Lock. 

The cs keyboard has two ADB connectors, otic for attaching it to the ADB port 
and one for connecting it lo the next device in the ADB chain. 
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Photo 1-2: The Apple Lies Keyboard 




The next device is usually the <;s mouse, For compatibility reasons, the GS treats 
the mouse as the port 4 device, even though il is really part of the ADB chain. The 
standard cs mouse contains iml> one button, hut the system software supports two- 
button mice. 



REAL-TIME CLOCK/CALENDAR 

The cs is the only member of the Apple il family with a built-in real-time clock/ 
calendar chip. With the help of a small battery on the motherboard, this chip keeps 
track of the current date and time, even after you have turned off the GS, 

The newest versions of the I'roDOS* operating system automatically recognize 
the GS eloek and will use it to time- and date-stamp Hies when they are saved to 
disk. You can also read flu- clock from a program tisintf two tool set Functions in 
ROM. To set the time, use the Control Panel. 

You can add a clock to a He, but most of the clocks being sold use up an expansion 
slot. The GS clock, on the other hand, does not occupy a slot (or a port), so you can 
a slot lor some other type of peripheral, 



S Exploring the Apple lies 



VIDEO DISPLAY MODES 

The GS supports all the standard video display modes of the lie and lie, plus one 
important new mode, The standard display modes are as follows: 

80-colunm text mode. The dimensions of the sereen are 80 columns by 24 rows. 

40-column text mode. The dimensions of the sereen are 40 columns by 24 rows. 

Low-resohition graphics mode. The dimensions of the screen are 40 dots hori- 
zontally by 48 dots vertically. Each dot can be one of sixteen colors. 

Double-low-resoliition graphics mode. The dimensions of" the sereen are 80 dots 
horizontally by 48 dots vertically. Each dot can be one of sixteen colors. 

High-resolution graphics mode. The dimensions of the screen are 280 dots 
horizontally by 192 dots vertically. Each dot can be one of six colors; color 
choices depend on the column in which the dot is found. 

Double-liiph-resulution graphics mode. The dimensions of the screen arc 560 
dots horizontally by 192 dots vertically. This mode supports sixteen different 
colors. 

The GS adds two minor embellishments to the te\t modes: the color of text characters 
and the background color are user-selectable. L'se the Control Panel to set them to 
any of sixteen colors. You can also use the Control Panel to set a screen border 
color. 

The new c;s video display mode is the super high-resolution graphics mode. It 
is trie mode used to display the outstanding color graphics images for which the GS 
has become famous. The super high-resolution screen is 200 dots in height. The 
horizontal dot resolution is separately controllable For each of the 200 lines, and can 
be 320 dots or 640 dots. Most programs keep all the lines at the same resolution to 
simplify graphics operations. 

The colors available in super high-resolution graphics mode depend on the hor- 
izontal resolution. In the 640-by~20G mode, each dot can be one of four colors 
selected from a group of sixteen assigned to the line. The foursome available depends 
on the column position, without using tricky programming techniques, only 256 
colors may appear on the screen at once. In the 320-by-200 mode, each dot can be 
one of sixteen colors; 256 colors may appear on the sereen at once. 

The colors used in super high-resolution graphics mode are completely pro- 
grammable and are formed by mixing one shade of red with one shade of green and 
one shade of blue. Because 16 shades are available for each of these primary colors. 
a total of 4,096 colors can be generated. 
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SOUND 

The cs has the most advanced sound capability of any microcomputer Tucked away 
in a comer of the motherboard is a powerful device, called an Ensoniq™ Digital 
Oscillator Chip (DOC), which is a professional-quality synthesizer for music, speech, 
and sound. This same chip controls the popular Mirage Music Synthesizer used by 
musicians around the world. 

By Feeding the Ensoniq chip the right software, you can create amazing audio 
effects, from symphonic sound to your own voice. The chip contains 32 oscillators 
fur stepping through audio waveform tables, so theoretically you can play back 32 
notes simultaneously. In the cs implementation, oscillators are paired off" to create 
15 generators or voices (the 16th generator is reserved for internal use); this is still 
enough to create superb sound quality. 

You can play back monophon ic sound on the GS through a two-inch on-board 
speaker or through the RCA mini headphone jack on the back panel. If you plug in 
headphones, the speaker is automatically disabled. To get stereo sound, you can 
add an inexpensive hardware demultiplexer, such as the SuperSonic card from 
MDldeas. Such a device samples the audio waveform output and the channel 
number (from 1 to 8). Stereo sound is then created by diverting the odd-numbered 
channels to one speaker and the other channels to the other speaker, Of course, it 
is up to the sound-generation software to direct the outgoing signal to different 
channels. 

The cs has a 64K RAM area that is used for storage 1 of waveforms, This RAM is 
not part of the 65816 address space, but can be read from or written to through a 
hardware interface called the Sound General Logic Unit (CLL 

The Ensoniq is also able to sample incoming analog waveforms and store them, 
in digital form, in its 64K RAM area. This is done by attaching the incoming sound 
source, such as a microphone, to an analog input connector and then triggering 
analog-to-digital conversions by sending commands to the Ensoniq chip. 



OPERATING SYSTEM SOFTWARE 

Over the past ten years or so, Apple has developed and released four major disk 
operating systems for the Apple II family, all of which work on the GS: 



DOS (1978) 
UCSD Pascal (1979) 
ProDOS 8 (1983) 
ProDOS 16 (1986) 



10 Exploring the Apple lies 



Other operating systems arc available from third-party developers, but only CP/M 
seems to generate niucli interest. CP/M does not work with a plain GS; you will 
need to install a Z-80 coprocessor card first. 

DOS 3.3, the latest (and final) version of Apples first operating system, is no 
longer active!) promoted by Apple. Nevertheless, it continues to be popular because 
there is a large body of software which works with it. DOS 3.3 does not take 
advantage of any special features of the c;s, and it does not work (without modifi- 
cation, with 3 l /a-inch disk drives or hard drives; it was designed to work only with 
544-inch drives and their associated 140k floppy disks. 

The L'CSD Pascal operating system is primarily for those who wish to program 
in Pascal. At one time. Pascal seemed to be the language of choice for educators 
because students are able to learn the fundamentals of a structured programming 
language quickly by writing a few programs in Pascal. Unfortunately, L'CSD Pascal 
has never received the widespread support which DOS 3.3 or ProDOS has. It is 
certainly rare to find a professionally published program for the Apple II written in 
Pascal. 

Apple released ProDOS S (H was originally called just "ProDOS") to solve the 
problem of using high-capacity disks with the Apple 11 family. Originally, this meant 
hard disks like the Apple ProFile™, hut the category now includes the 800K 3 l A- 
ineh disks used by the Apple 3.5 Drive and the UniDisk 3.5, ProDOS 8 works 
nicely with disk volumes up to 32 megabytes \md with files up to 16 megabytes. In 
addition, it uses a hierarchical directory structure to make it easier to manage the 
hundreds ol files which can be stored on high-capacity disks. 

ProDOS 16 is the only Apple II operating system that works only on the CS, 
Although it uses the same disk file storage format as ProDOS 8, you must use 
different programming techniques to control it. This means ProDOS 8 applications 
will not work under ProDOS 16. and vice-versa: however, you can store files created 

either operating system on the same disk. 

Apple developed ProDOS 16 for the c;s because ProDOS 8 works only with 
programs that run in the first H4K of memory. This is an unreasonable restriction 
in a system, like the GS, that has a 16-megabyte address space- With ProDOS 16, 
you can issue disk commands from anywhere in memory. 

ProDOS 16 is described in greater detail in chapter 10. For an in-depth analysis 
of ProDOS s> refer to the book AppleProDOS: Advanced Features for Programmers 
(Little, 1985). Other useful books are listed in appendix 8. 

DEVELOPMENT SOFTWARE 

The official development software for the GS is the Apple Programmer's Workshop 
(APW). It runs under ProDOS 16 and is distributed on HOOK disks, so you will need 
at least one ^Vli-inch disk drive to use it. 

APW is made up of several integrated modules accessed through a common 
command shell: 
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• A text editor for creating program source code 

• A linker For combining object code modules created by APW-compatibJe 
assemblers and compilers 

• A 65816 assembler ft* compiling assembly language programs 

• A 65816 debugger for tracking down errors in programs 

An \PW-compatible C compiler is also available from Apple. Similar compilers lor 
Pascal and BASIC arc available from third parties or are hi development, {See 
appendix 8. 

The APW shell supports many commands that will help you perform common 
software development tasks, such as moving files from disk to disk, renaming files, 
deleting files, and displaying the names of on-line volumes. 

CREDITS 

So who was responsible for designing the GS, anyway? The answer is as close as 
your keyboard, Remove the disk from your start-up drive and turn on (or reboot) 
the cs. A "Check startup device!" error message will appear on the screen along 
with an apple icon that slides back and forth, Now for the secret command: while 
holding down the Open-Apple arid Option keys, type Control-N. This tells the CS 
to reveal the mimes of all the key people who worked on the GS project. You read 
it here lirst. 



12 Exploring flu- Apple IlGS 



CHAPTER 2 



Programming 
the 65816 
Microprocessor 



The 65816 microprocessor that controls tin cs ran operate in cither emulation mode 
or native mode. In emulation mode, the 65816 understands the same instructions 
(and some new ones, too) as the 65C02 microprocessor in the Apple He and the 
enhanced Apple He. Because the GS hardware can emulate the characteristics of 
the lie and He almost exactly, this means most lie and 13c software will work on 
the cs without modification. 

Note: For convenience, consider future references to the He as references to the 
Ik as well. 

In native mode, the 65816 supports many new and important features that make 
it substantially more powerful than a 65C02: 

• A directly addressable L6-megabyte address space 

• 16-bit accumulator and index registers 

• 16-bit memory operations 

• A relocatable stack and direct page 

• Many extra instructions and addressing modes 

By exploiting these features, developers can create powerful programs much more 
easily than they could on a lie with a 65C02. Refer to the manufacturer's 65816 
data sheet in appendix 2 for a detailed description of the microprocessor. 

The 65816 in the CS is able to operate at either of two speeds: the normal 1.0 
MHz rate of the lie or the faster rate- of 2.8 MHz. (Overhead lor RAM refreshing 
actually reduces the average fast rate from 2.8 MHz to 2 5 MHz for RAM operations; 
ROM operations take place at full speed) The faster speed is the default, and most 
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programs will run properly at that speed. Some lie applications, however, notably 
those that rely on precise timing loops (games and simulators, for example), may 
work only al normal speed. You can change the current operating speed with the 
Control Panel System Speed command. 

This chapter investigates how the 65816 operates. This includes an examination 
of its internal registers, its instruction set and addressing modes, and two important 
data areas called the stack and direct page. Methods of creating 65816 programs 
using the APW assembler are also covered. Throughout the chapter the emphasis 
is on features unique to the 65816 running in native mode, but references to 65CQ2 
emulation mode features are made where necessary. 



THE 65816 MEMORY SPACE 

The 65816 has a 24-bit address bus, meaning it can access an enormous 16-megabyte 
(2 2i bytes) memory space. Internally, it deals with this memory as u series of64K 
banks, numbered from $00 to $FF. A standard r.s has BAM in banks $00, $01, $E0, 
and SE1 and ROM in banks $FE and $FK Chapter 4 discusses exactly how the GS 
makes use of its memory space. 

The first bank, bank $00, lias special qualities, ll contains two interesting data 
areas called the dired page and the stack. In native mode, you can place these 
areas anywhere in bank SOO. In emulation mode, the stack must be in page S01; 
the direct page can be any page in bank $00, but is invariably page $00 (zero page). 
(A page is a group of 256 consecutive bytes beginning at an address whose last two 
dibits are $00.) 



Direct Page 

The 256-byte direct page is Important because those 65816 instructions that make 
use of it are shorter and fester than similar instructions using other parts oi memory, 
That is because the program needs to provide only one byte of address information 
to lli< 65816 (the offset into the direct page); the other two bytes needed to form a 
complete 24-bit address are taken from an Internal register. 

More importantly, the 65816 has powerful Indirect indexed addressing modes 
that require you to place a pointer to a data structure in direct page. To access a 
field in the data structure, all you have to do is specify the direct page location and 
Ifset to the field. Unlike some microprocessors (notably the 68000), the 65816 
does not allow von to access a data structure indirectly by putting its address in a 
microprocessor register; this makes it necessary to have a data area such as a direct 

page. 

When you are developing programs in emulation mode, it is common to refer to 
direct page as zero page, because it should be located at page $00 in bank $00. as 
it is when using the 65C02. 
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Stack 

The* stack is an area of memory thai is implicitly used by certain 65816 instructions 
to store data. This area is "inverted" in the sense that it prows down in memory as 
you add data to it (a "push" operation) and shrinks up in memory as you remove 
data from it la "pull" operation). 

The active position in the stack is given by the value in a 16-bit stack pointer 
ISPJ register, described below. It is initially set to the last byte (highest-addressed 
byte) in the stack area. 

It is important to understand the mechanics of push and pull operations, because 
they are used quite often. When you push a byte value on the stack, the byte is 
placed at the address that is in the stack pointer and the stack pointer is decremented 
by one. When a byte is pulled from the stack, the stack pointer is incrernented and 
the value is loaded from the new address it contains. The important point to realize 
is that the stack pointer always points to the byte just below the last item pushed 
on the stack. 

In native mode, the stack could occupy the whole ol bank $0(1. although must 
programs never need more than a page or two. In emulation mode, the stack is 
always 2.56 bytes long and occupies page $01 of bank SOO. 

THE 65816 REGISTERS 

Registers are areas inside a microprocessor that the microprocessor uses to store 
values and manipulate data, Ihey are not memory locations in the microprocessors 
address space In general, the more registers a microprocessor has. the more 
powerful (he microprocessor is; that is because operations involving registers are 
much taster than similar operations involving memory locations. 

The registers used by the 65816 are shown in figure 2—1. There are nine of them: 

• Accumulator 

• \ index register 

• Y index register 

• Data batik register 

• Program bank register 

• Direct page registet 

• Pro tatus regtstei 

• Stack pointer 

• Program counter 
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Figure 2-1. The 65816 Register Sets in Emulation Mode and Native Mode- 



65C02 
emulation mode 

7 



Accumulator 

X Index Register 

Y index Register 
Data Bank Register 
Stack Pointer 

Direct Page Register 

Program Counter 

Program Bank Register 
Status Register 



A 



65816 

native mode 



01 



PC 



15 




7 






Q 




A 
B 


or 


c 


A 


| 


15 




7 









1 


15 




7 









Y 

i 1 



23 16 





15 







00 




5 

1 


1 




15 







00 




D 











! 5 









16 


PC 


23 




7 






K 


















Processor Status Register 



The p. status register (P) contains a prnup of status Hags and mode select 

bits that reflect the operational state of the 65816 (see figure 2-2). Most instructions 
cause one or more status flaps to change according to the operations they perform; 
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Figure 2-2. The Status Flags in the 65816 Processor Status Register 
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status-checking instructions can then be used to change the flow of a program 1 
on the result. 

The structure oi the status register depends on whether the processor is in 
emulation mode or native mode, as figure 2-2 indicates. The flags in the emulation 
mode status register are the carry Bag, the zero flag, the IRQ disable flag, the 
decimal mode Bag, the I weak flag, the overflow flag, the negative Hag, and the 
emulation Hag. In the native mode status register, the break flag is not present, the 
spare status bit is used, and two register-select flags are available: the memory/ 
accumulator select flag and the index register select flag. The flags in the emulation 
mode status register and the native mode status register are discussed below. 



Carry Flag. The carry flag is most often used when perioruhiig addition i.UJCi 
or subtraction (SBC) operations. As is shown later in this chapter, this Hag must be 
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cleared (with CLC) before adding two numbers and must be set (with SEC) before 
subtracting two numbers. 

The carry Bag is also used to check the result of a comparison operation (CMP, 
CPX, CPY). II the number in the specified register is less than the number it is 
being; compared to, the earn,' flag is cleared, otherwise it is set, The BCC and BCS 
branch-on-conditinn instructions can then be used to switch control to another part 
of the program depending on the result. 

The carry Hag also participates in the shift and rotate instructions: ASL T LSR, 
ROL, and ROR. These instructions are described later in this chapter. 

Zero Flag. The zero flag indicates whether the result of the last arithmetic oper- 
ation or register loading operation was zero. II it was, the zero flag is set to 1; 
otherwise, it is cleared to 0. 

IRQ Disable Flag, The IRQ disable flag controls how the 65816 reacts to hardware 
interrupt request (IRQ) signals, (Interrupts are discussed later in this chapter) If 
the flag is set to 1. IRQ interrupts are ignored, otherwise the 65816 processes them. 

Decimal Mode Flag. This flag controls the types of numbers the 65816 uses to 
Min addition (ADC) and subtraction (SBC) operations. When the decimal mode 
i\,v£ is off, standard binary arithmetic rules are used. Tins is the mode in which most 
programs operate and it is the default mode when the CS is turned on. 

When decimal mode is on, the 65816 assumes all numbers are stored in binary- 
coded decimal format and generates arithmetic results that are in this format as 
well. In this format, each byte contains exactly two digits from to 9; the most- 
stgnificanl digit occupies the high-order four bits of the byte. 

Break Flag. The break flag indicates whether the source of a 65816 interrupt in 
emulation mode is a BRK instruction (the Bag is set) or a hardware interrupt request 
(the flag is clearK Unlike native mode, BRK and interrupt requests vector to the 
same subroutine; the Subroutine can inspect the break flag to determine the cause 

i the interrupt. 

Overflow Flag. The overflow flag usually indicates whether the result of an arith- 
metic operation involving two's-complement (signed) numbers is within prescribed 
limits. The 6.5816 uses the two's-complement form for signed arithmetic operations 
to simplify internal calculations. The limits are -128 to +127 for 8-bit numbers and 
-32768 to +,32767 for 16-bit numbers, 

iln most-Significant bit of a two's-complement number is the sign bit: it is for 
positive numbers and 1 for negative numbers. For positive numbers, the remaining 
bits represent the magnitude of the number in standard binary form. 
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Things are not quite so simple for negative numbers. To determine the two's- 
complen .ent form, take the absolute value of the number, complement it, then add 
1 to the result. Here is how to form -22, for example: 

00 010110 (+22 in binary) 

111010 01 ( + 22 complemented) 
* 1 (add 1) 



11101010 (-22 in twos-complement form) 

Notice that the high-order hit is set, identifying this as a negative nut: 

Negative Flag. This flag reflects the value of the high-order bit of the last value 
transferred directly to the A, X, or V register or put there as a result of a calculation. 
The high-order bit is bit 7 for an 8-bit register or bit 15 for a 16-bit register. 

The negative flag derives its name from the fact that the high-order bit of a twos- 
complement number reflects its sign: if the hit is 1. the number is negative. 

Emulation Flag. The emulation flag hides behind the carry flag in the status 
register. You will use it to set the operating mode of the 65816. When it is set to 
1, the 65816 operates in 65CG2 emulation mode: when it is 0, the 65816 operates 
in native mode. 

Entering native mode paves the way to powerful 16-bit register and memory 
operations, as is discussed below. 

The only way to affect the emulation bit is to set or clear the carry flag (with 
SEC orCLC) and then execute the XCE (exchange carry with emulation) instruction. 

Register Select Flags, There are two register select flags in the native mode status 
register: the memory/accumulator select flag and the index register select flag. 

The index register select bit is called x and the memory/accumulator select bit is 
called m. When x=l the 65816s X and Y registers are both 8 bits in size; when 
x=0, these index registers are 16 bits. Similarly, when m=\ the A register is 8 bits 
in size and all memory operations (such as DEC:. L\C r ASL, and others) involve 
one byte only. When m=Q t the A register is 16 bits in size and memory operations 
act BD two consecutive bytes (a word). 

When the hi and x bits are both 0, the 65816 is said to be in fiill native mode. 
This is the mode you will usually want to use when you develop a GS -specific 
application. 

The 65816 has two special instructions you can use to set or clear the m and x 
bits: REP and SEP. To clear bits, use the REP instruction: 

REP #XQQ110000 ;clear m and x bits 
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Note: As is discussed later in this chapter, the # symbol means the number is a 
constant, not an address; % identifies the number as a binary number. 

REP clears to those bits in the status register that correspond to 1 bits in the 
operand. (The operand is the number following REP.) Thus, you would use REP to 
activate 16-bit register/memory and indexing operations. 

Conversely SEP sets to 1 those bits in the status register that correspond to 1 
bits in its operand. Use SEP lo revert to 8-bit register/ memory and indexing 
operations. 

Accumulator 

The accumulator (A) is an 8-bit or a 16-bit register, depending on the state of the 
m flag in the native mode status register. (Actually, even in 8-bit mode you can 
access the "other" 8 bits of the accumulator with the XBA exchange instruction,) In 
emulation mode, the accumulator is always 8 bits in size 

The accumulator is the only register that works with the 6o816s addition (ADC) 
and subtraction (SBC) instructions. In fact, that is how it gets its name: it accumulates 
the results of arithmetic operations. It is also the only register which participates m 
logical operations (ORA, AND, XOR). 

Most instructions refer to the accumulator by the symbol A, no matter what Us 
size. Some call it C to emphasize that they act on the entire 16 bits even ,f the m 
flag is 1 The two halves of the 16-bit registers are also referred to as A (low 8 bits) 
and B (high 8 bits). This is for the benefit of the XBA instruction, which swaps the 
two halves of the 16-bit accumulator. 

Using a 16-bit accumulator is convenient because it can handle numbers up to 
65 535 (instead of just 255), thus simplifying many types of arithmetic instructions. 
A 16-bit accumulator is somewhat less convenient for dealing with character 
strings however, because you usually want to load only one character mto the 
accumulator at once. In these situations, you may want to temporarily revert to an 
8-bit register using the SEP #%001000OO instruction. 

Index Registers 

The index registers are called X and Y. They are commonly used to hold offset; into 

a data structure from a fixed reference location; hence the name index. 

Like the accumulator, the index registers are 8 bits in size in emulation mode. 
In native mode, thev can be cither 8 bits or 16 bits in size, if the x flag is 0, they 
are 16-bit registers; if it is 1, they are 8-bit registers. 

Note that the x flag always affects both index registers: it is not possible to have 
X and Y registers that are different sizes. 
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Stack Pointer 

The 16-bit stack pointer register (SP) points to an address in hank S00 that is one 
byte below the address of the last value pushed on the stack. It automatically 
decreases after push instructions, such as PHA and PJ IX, and increases after pop 
instructions, such as PLA and PLX. 

In emulation mode, the high-order byte of the stack pointer is always $01, so the 
stack is confined to 256 bytes. 

Direct Page Register 

The 16-bit direct page register (D) contains the address of the start of the direct 
page in bank $00. it can contain any value, hut direct page operations are faster if 
direct page begins on a page boundary In emulation mode, the direct page register 
should be set to S0O. 

Data Bank Register 

Tin 8-bit data bank register (B.I indicates the default memory hank for memory 
access operations. When you specify a 16-bit address in an instruction, the 65816 
calculates the full 24-bit address by concatenating the data hank register. In emu- 
lation mode, the data bank register should he set to $00, 

Program Bank Register 

I In program hank register (K) is an 8-bit register that indicates in which memory 
hank the current program is operating. It combines with the 16-bit program counter 
register to mark the exact position in memory of the instruction currently being 
executed* 

There is no explicit instruction for changing the program bank register. It im- 
plicitly changes when the program transfers control to another bank with a JSL or 
JMP instruction. 

In emulation mode, the program bank register should be set to $00. 

Program Counter 

The 16-bit program counter (PC) holds the offset from the start of the current 
program bank ol the instruction currently being executed. The 65816 automatically 
increments the PC as it processes instructions, usually by adding the size of the 
instruction just executed. When a flow of control instruction such as JMP or BRA 
is encountered (see below I, however, the operand address is put into the PC, causing 
execution to continue at the target address. 
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Note that when the PC changes from $FFFF to $0000 at a memory bank bound- 
ary, the program bank register is not incremented. This means that control passes 
to the beginning of the current bank, not to the beginning of the next bank. As a 
result, a 65816 program is not permitted to cross a bank boundary, although it can 
call a program or subroutine in another bank. On the OS, the ProDOS 16 program 
loader always loads a program into a single bank. 

THE 65816 INSTRUCTIONS 

The 65816 supports 91 different instructions. (See appendix 2 for detailed descrip- 
tions of each.) This includes every 65C02 instruction as well as 27 instructions 
unique to the 6.5816. Each instruction may use one or more addressing modes to 
locate data it uses; the number of instruction/addressing mode combinations is 256. 
You will find a description of addressing modes in the next section. 

A one-byte binary opcode tells the 65816 what the instruction is and what 
addressing minle it is using. You do not have to memorize these opcodes, because 
you will use an assembler to convert mnemonic instructions and addressing modes 
in a source code file to binary object-code lorm. 

Following the opcode there may be up to three operand bytes describing a 
number or an address to be used by the instruction. Multibyte operands arc always 
stored with the low-order byte first. Again, the assembler takes care of arranging 
these bytes properly for you. 

The next section of this chapter examines the 65816 instructions, discussing what 
they do, and how they should be used. Refer to table R2-L (in the reference section 
at the end of the chapter) for an alphabetical list of instructions. This table also 
contains the permitted addressing modes and opcodes for each instruction type as 
well as the number of cycles the 65816 uses to complete each instruction. 

(The time for one cycle is the reciprocal of the clock speed. The clock speed is 
either 2.8 MHz or 1.0 MHz, depending on the setting of the Control Panel System 
Speed option. For programs operating in RAM in fast mode, the average clock 
speed is actually about 2.5 MHz because of overhead introduced by RAM refreshing 
requirements.) 

Note: Instructions marked with an asterisk in the following sections are not 
supported by the 65C02 microprocessor. 

Load/Store Instructions 

LDA I .oad the accumulator (byte or word:' 

LDX Load the X register (byte or word) 

LDY Load the Y register (byte or word) 

ST A Sinn- the accumulator [byte or word) 

5TX Store the X register (byte or word) 

STY Si. ire the Y register (byte or word) 

STZ Store -zero to memory (byte or word) 
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The first three instructions. LDA, LDX, and LDY, let you load 8- or 16-bit values 
into the accumulator and index registers. The data size depends un the settings of 
the m and v hits in the 65816 status register. The value can be a specific number 
or a number stored at a given memory location. 

The STA, STX, and STY instructions let you transfer the contents oi a register 
to a particular memory location STZ stores a zero at a memory location. 

When loading word-sized values from a given address, keep in mind that the 
low-order 8 bits of the register are filled with the number stored at Address and 
the high-order 8 bits are filled with the number stored at Address+ 1 (the next 
higher address). Similarly, when storing words, the low-order S bits of flic register 
are stored first. 

Push Instructions 

*P£A Push effective absolute address (word) 

*PEI Push effective indirect address (word) 

*PER Push effective relative address (word) 

PHA Push the accumulator (byte or word) 

*PHB Push the data bank register (b) I' ' 

*PHD Push the direct page register (word) 

*PHK Push the program bank register (byte) 

PHP Push the status register (byte) 

PHX Push the X register (byte or word) 

PHY Push the Y register (byte or word] 

Use the push instructions to transfer data to the top of the stack and decrement the 
stack pointer by the data size. The data size is either byte or word, depending on 
the instruction and the settings of the m and x status bits. Word operands are pushed 
high-order byte first, 

PHA, PHB, PHD. PHK, PHP, PHX, and PHY all push the contents of a register 
on the stack. PEA, PEI, and PER push two-byte addresses, as follows: 

PEA pushes an absolute Lfc-bit address; most programmers really use it to push 
numeric constants, however, because it does not involve loading the constant 
into a register first. 

PEI pushes the address stored in two consecutive direct page locations. 

PER pushes the address, which is a specified number of bytes from the position 
of the instruction. This instruction is useful il you are developing relocatable 
code (code that runs at any load address). 

The operand for a PEA, PEI, or PER instruction gives the 65816 the address it 
needs to work with, 
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Pull Instructions 

PL A Pull the accumulator (byte or word) 

# P L B Pull data bank register (byte) 

*PLD Pull direct page register (word) 

PLP Pull status register (byte) 

PL X Pull X register (byte or word) 

PLY Pull Y register (byte or word) 

Those inductions transfer data from the top of the stack to a register. J«M^ 
the stack pointer by ooe (byte operation! or two (word operat.on). Word operands 
are popped low-order byte first. 

Inter-register Transfer Instructions 

TAX Transfer A to X 

TAY Transfer A to Y 

TSX Transfer S to X 

T X S Transfer X to S 

T X A Transfer X to A 

TYA Transfer Y to A 

*TCD Transfer C to D 

#TDC Transfer D to C 

• TCS Transfer C to S 

*TSC Transfer S to C 

*TXY Transfer X to Y 

#TYX Transfer Y to X 

Note: D - databank register; (- - 16-bit accumulator 

The inter-regiSter transfer instructions let von move data horn ^^ J^^ 
Special reasons lor wanting to do this are to initiate the stack pomter ( 1 XS. TCS) 

be^Ssters ofdutcn, ^ K«. TXA u,H TYA. ^[^^^ 
order 8 bits of the accumulator (B) is zeroed; if x=0 and m- U B "■ « n tAcM 
For TAX and TAY if m = I and 1=0. the B register is transferred to the upper 8 bit 
SXStS^ tf -0 and x- 1. the upper M of the index raster are not 
affected. For TXS. the high-order stack register byte is zeroed il x 1. 
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Exchange Instructions 

• XBA Exchange B and A 

■ XCE Exchange earn and emulation bits 

The two exchange instructions involve manipulating bits inside registers. XBA swaps 
the upper half of the 16-bit accumulator (B) with ihe lower half. XCE swaps the 
carry bit of the status register with the emulation bit so that you can switch between 
native and emulation mode, as explained earlier in this chapter. 

Block Move Instructions 

*MVN Move block in negative direction 
*MVP Move block in positive direction 

The block move instructions are powerful instructions that let you transfer a hlock 
of data from any part of memory to any other (at least if you are in full native mode! 1 . 
For MVN, X and Y must contain the starting addresses of the source and destination 
blocks; the length of the block, minus one, must be in the 16-hit C register (even 
if the m flag is not 0), The source and destination banks are specified in the operand 
for the instruction. MVN moves data from the source block to the destination block 
in increasing address order. 

H the source and destination blocks overlap and the destination block begins at 
a higher address, do not use MVN, because the end of the source block will be 
overwritten before its data is moved. In this situation, use the MVP instruction 
instead. It moves data from Ihe end of the block to the beginning. (Of course, you 
would not use MVP if the blocks overlap and the destination block begins at a lower 
address.] 

To use MVN, place the ending address of the source and destination blocks in X 
and Y; as with MVP, the count minus one goes in C. 

Flow-of-control Instructions 

BCC Branch il carry Hag is clear 

BCS Branch if carry Hag is set 

BEQ Branch if zero flag is set (equal) 

BM I Branch if negative flag is set (minus) 

BNE Branch if zero flag is clear (not equal) 

BPL Branch if negative flag is clear {plus) 

BRA Branch alwavs 

*BRL Branch always (long form) 
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BVC Branch if overflow Bag is clear 

BVS Branch if overflow flag is set 

* JML jump to long address 

J MP Jump to absolute address 

* JSL jump to subroutine Ions, saving return address 
JSR Jump to subroutine, saving return address 

*RTL Return from subroutine long 

RTS Return from subroutine 



When the 65816 executes a program, it usually processes instructions in the order 
to which they appear in the program. You can use the flow of control instructions 
to tell the 65816 to jump or branch to any position in a program, either uncondi- 
tionally or only if a certain condition is true. 

JML, JMP, BRA T and BEL are unconditional instructions; they always direct the 
65816 to another portion of the program. JMP transfers control to a specific memory 
address BRA and BRL perform branching relative to the current address in the 
program counter. The range of a BRA branch is -128 to +127 bytes from the start 
of the next instruction in the program. BRL brandies are from -32768 to +32767, 
So you can use BRL to move to any part of the current program bank. 

The 65816 also supports conditional branching, in which the decision on whether 
to change the flow of control depends on the selling of flags in the status register. 
These are the BCC, BCS, BEQ. BM1, BNE, BPL, BVC. and BVS instructions. 
Use them after anv operation that aftects the flags so that you can lake different 
actions depending on the result. Refer to table R2-1 to determine how each instruc- 
tion affects the processor status Hags 

For example, alter a CMP (compare,! command, the carry flag is set il the number 
in the accumulator is greater than or equal to the number in the operand. Thus, 
you could use a BCS instruction tu transfer control to the portion of the program 
that deals with this situation. 

If a program needs to perform the same task again and again, it is best to convert 
the task to a callable subroutine so that its code does not have to be repeated. To 
call a subroutine you can use the JSR or JSL instructions, depending on whether 
the subroutine ends with RTS or RTL. If the subroutine is in another code bank. 

you must use JSL. 

Both JSR and JSL push on the stack the address, minus one, of the next instruc- 
tion in the program. For JSR this is an offset from the start of the current program 
bank (two bytes); for JSl.it is a long absolute address (three bytes). The subroutine 
must end with either an RTS instruction (if called with JSR) or an RTL instruction 
(if called with JSL). RTS and RTL pop the return address put on the stack by JSR 
and JSL. put it in the program counter i JSL also updates the program bank register), 
and increment the program counter. This causes execution to resume at the instruc- 
tion following the JSR or JSL. 
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Arithmetic Instructions 

ADC Add memory to accumulator with tarry 

CMP Computer accumulator with memory 

CPX Compare X register with memorj 

CPY Compare V register with memon 

DEC Decrement the accumulator or memory 

DEX Decrement the X roister 

DEY Decrement the Y register 

INC Inctement tin- accumulator or memory 

I NX Increment the X register 

I NY Increment the Y register 

SBC Subtract memory From accumulator with cum 

You can use INC;. I\X. and INY to add one to the value in the accumulator or an 
index register. (INC also works with memory locations.) The largest number a 
register can hold is SFF (8 bit) or $FFFF (16 bit); the register rolls to $00 if von 
increment il in these situations. 

The corresponding decrement instructions are DEC:, DEX, and DEY. They roll 
the contents of the registers backwards through to SFF {& bit) or $FFFF (16 bit). 

You can add or subtract numbers other than one from the accumulator with the 
ADC and SBC instructions. To add with CLC. you must remember to clear the 
cam flag first and to add multiword (or multibyte) numbers starting with the low- 
order word. For example, to add $1AD88 to tin long word stored from Address to 
Address Ki. u.se code like this: 



CLC 








LDA 


Address 


; (assume 1 6-bi t 


A) 


ADC 


#$1 AD88 


; low word 




STA 


Address 






LDA 


Address*2 






ADC 


#**1 AD8B 


■* - high word 




STA 


Address+2 







Subtraction is similar to addition except that yon must start with a SEC instruction 
before performing a scries of SBC operations 

The compare instructions, CMP, CPX. and CPY, are really subtraction instruc- 
tions in disguise . The difference is that the result of the subtraction is not stored 
anywhere; they simply cause Bags in the status register to change depending on the 
result. The Hag settings are as follows: 

The zero flag is set if the two numbers are the same. 

The earn' Hag is set if the (unsigned) number in the register is greater than or 
the same as the number being compared. 
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The carry flag is clear if the (unsigned) number in the register is less than the 
number being compared. 

You can use the In anch-on -condition instructions to change the flow of control after 
a comparison operation. 

Logical Instructions 



AND 


Logical AND 


EOR 


Logical exclusive -OR 


ORA 


Logical OR 



Logical instructions combine the value in the accumulator with the value in the 
operand in accordance with the rules of Boolean algebra- The result is stored in the 
accumulator. 

For AND operations, all bits m the accumulator that correspond to bits in the 
Operand are cleared to 0; other bits are unaffected. With ORA T all bits in the 
operand that correspond to 1 bits in the operand are set to I, other bits are 
unaffected. The EOR operation is more complicated than either AND or ORA. It 
sets to 1 all bits that are 1 in the accumulator and in the operand or vice-versa. 
Bits that are the same in value are cleared to 0, 

Bit -manipulation Instruction* 

B I T Test bits 

TRB Test and reset bits 

TSB Test and set bits 

The BIT instruction performs two functions at once. First, it transfers the high- 
order two bits of the operand to the negative and overflow flags in the status register 
(but only if the operand is not an immediate number). If these two bits store program 
Hags yon can follow the BIT with BMi to branch if the high-order bit is set, or 
with BVS if the ncxt-to-high-order bit is set. 

The second function of BIT is to logically AND the contents of the accumulator 
with the value of the operand. The result is not stored, but the zero flag is condi- 
tioned by the operation. This is a handy way of determining if certain bits are clear 
or set without destroying the contents of the accumulator For example, to test bits 
and 1, use the instruction: 

BIT #10000001 1 

If either o^ the last two bits in the accumulator are 1, the zero flag is not set and a 
subsequent BNK branch will succeed. 

You can set or clear any group of bits in an operand with the TRB and TSB 
instructions. TRB clears to those bits in the operand that correspond to 1 bits in 
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the accumulator. Conversely, TSB sets these bits to 1. TRB and TSB also logically 
AND the accumulator with the operand and set the zero flag according to the result. 
The result itself is not stored. 

Shift-and-rotate Instructions 

ASL Arithmetic shift Ml 

LSR Logical shift right 

ROL Rotate left 

ROR Rotate right 

The shift and rotate instructions let you manipulate the bits in the accumulator or 
in a memory location by shifting them left or right. 

ASL moves the bits in the operand one position to die left. The high-order bit 
moves into the carry flag of the status register and a appears in bit of the 
operand. ROL is the same as ASL. except that it is the initial value of the carry flag 
that is put in hit 0. 

LSR moves bits in the operand one position to the right, with bit moving into 
the earn' flag. A appears in the high-order hit of the operand. ROR is the same, 
except that the initial value of the earn Hag is put in the high-order bit 

The operand size lor shift and rotate instructions IS either 8 hits or 16 bits, 
depending on the status of the m hit in the status register. 

System-control Instructions 

BRK Break (software interrupt) 

R T I Return from interrupt 

NOP No operation 

SEC Set carry flag 

C L C Clear carry flag 

SED Set decimal flag 

CLD Clear decimal flag 

SE I Set interrupt flag 

CL I Clear interrupt flag 

CLV Clear overflow flag 

*SEP Set status register bits 

* R E P Rese t status register hits 

*C0P Co-processor t software interrupt) 

*STP Stop the clock 

*WA I Wait for interrupt 

•WDM [Reserved for expansion] 

The system control instructions perform a variety of miscellaneous operations. One 
group (SEC, CLC, SED, CLD, SE1, CLL CLV, SEP. and REP) can be used to 
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explicitly set or clear bits in the status register. The main use of SEP and REP is 
to set and clear the m and x bits in the status register, as explained above. 

NOP is a "do-nothing" instruction that simply acts as a place-holder in a debugging 
operation or a time-waster in a timing loop. 

S IT, WAI. and WDM are instructions you will probably never need to use. STP 
essentially shuts down the 65816 until a system reset occurs. WAI puts the 65816 
into a low-power mode and then waits until a 65816 interrupt occurs before passing 
control to the next instruction in the program. The WDM instruction is reserved 
for future expansion of the 65816 instruction set 

The BRK, COP, and RTI instructions are related to 65816 interrupts and will be 
discussed later in this chapter. 

THE 65816 ADDRESSING MODES 

An addressing mode describes the technique the 65816 uses to locate the data with 
which an instruction needs to work. In a 65816 program source file, the addressing 
mode information appears in the operand field, just after the instruction mnemonic. 
The assembler format for each addressing mode is shown in table 2-1. 

Knowing the addressing mode, the 65816 can use the operand to calculate an 
effective address (EA) for the instruction. For read operations, the EA is the address 
from which data is read; for write operations, it is where data is stored. The effective 
address calculation varies with the addressing mode, of course: it may be a simple 
absolute address, an address calculated by adding the contents of the X register to 
a base address, an address pointed to by two locations in direct page, and so on. 
The availability of so many different addressing modes makes it easier to develop 
efficient programs. 

This section investigates the various addressing modes you can use with the 
65816. Keep in mind, however, that not all addressing modes can be used with 
every instruction. To see if a particular combination is permitted, refer to table 
R2-I. 

Implied 

Many instructions do not require an explicit indication of addressing mode because 
the instruction mnemonic completely describes what needs to be done. These 
instructions use the implied addressing mode. 
Examples of such instructions are as follows: 

SED NOP TAX TSX WAI 



CLV 


CLD 


TAY 


TXA 


WDM 


SEI 


CL1 


TCD 


TX5 


XBA 


cue 


SEC 


TC5 


TXY 


XCE 


INK 


1NY 


TDC 


TXA 




DEX 


DEY 


TSC 


TYA 





This list includes every instruction that explicitly sets or clears specific status flags. 
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Table 2-1; The Assembler Formats of the 65816 Addressing Modes 


Name of Addressing Mode 


Assembler 

Format 


Implied 


— 


Accumulator 


A 


Immediate 


#imniediate 


Program Counter Relative 


rel 


♦Program Counter Relative Long 


longrel 


Stack 


— 


♦Stack Relative 


sr.S 


* Stack Relative Indirect Indexed with Y 


isi.SJ.Y 


* Block Move 


srcbnk.destbnk 


Absolute 


add r 


Absolute Indirect 


(addr) 


Absolute Indexed with X 


addr.X 


Absolute Indexed with Y 


addr.Y 


Absolute Indexed Indirect 


(addr.X) 


""Absolute Long 


long 


♦Absolute Long Indexed with X 


long,X 


♦Absolute Indirect Long 


laddrj 


Direct Page 


dp 


Direct Page Indirect 


(dp) 


Direct Page Indexed with X 


dp.X 


Direct Page Indexed with Y 


dp.Y 


Direct Page Indirect Indexed with Y 


(dp).Y 
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Table 2-ls Continued 






Assembler 


Same of Addressing Mode 


Format 


Direct Page Indexed Indirect with X 


idp.X) 


•Direct Page Indirect Long 


[dp] 


•Direct Page Indirect Long Indexed with 1 


[dpU 


A = accumulator 


ongrel = 16-bil onset address 


uddr = 16-bit address 


inimluT = S- or 16-bil constant 


destbnk — bank number 


rel = Hdiil offset address 


dp = direct page address 


sr — slack pointer offset 


lonj; = 24-bit address 


srebnk = bank number 


note: Addressing modes not supported bj the 654 dZ 


ore marked wiili asterisks. 



Accumulator A 

The accumulator addressing mode is used by those instructions that manipulate the 
contents of the accumulator hut that do not need to be supplied with an address or 

(lata Here are some examples; 



LSR 


RDL 


ASL 


ROR 


INC 


DEC 



To select this addressing mode, put the letter A in the operand field. 



Immediate #immediatc 

The immediate addressing mode is used when the operand is a numeric constant. 
The assembler format fur this mode is #immediate. That is. precede the number 
M.r .l symbol for a number) with the # symbol. 
Here are some examples: 

LDA #23 ;Decimal number 

LDX #SAEF2 •, Hex numbers begin wiLh $ 

CMP #X0OOQ011Q ;Binary numbers begin with X 

REP #120 

ADC #256 
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Do not forget to include the # symbol when using this mode. If you do forget, the 
assembler thinks you are referring to an address and will deal with the numbei al 
that address, not the constant itself. 

Program Counter Relative 

This addressing mode is used In the 65S16 branch -on -condition instructions: BCC, 
BCS, HEQ. BMI, BNE, BPL, BRA, BVC, and BVS, For this mode, the operand 
represents the offsel to a target address, measured from the instruction following 
the branch instruction. This offset must be a signed value from -128 to +127, 
Transferring control to a target outside this range is possible only with unconditional 
J\1P or BKL instructions. 

When using this mode, it is not necessary for you to calculate the offset. Simply 
specify the address of the target location in the operand field of the instruction by 
referring to its label, as follows; 

BCC MyTarget ^Branch to labelled address 

MyTarget NOP 
The assembler calculates the offset for you when assembling the file. 

Program Counter Relative Long 

This addressing mode is used by the BR1. and PER instructions only. For this mode, 
the operand is an offset from the start of the following instruction to a target address. 
The offset range is from -32768 to +32767, so you can access any location in the 
current bank. (Wraparound within a bank occurs if the offset is past the end of a 
bank. ) 

As with the program counter relative mode, you need only specify a target address 
when writing a program, the assembler will calculate the actual offset for you. 

Stack 

The stack addressing mode is really a variation of the implied mode, because thi 
instruction mnemonic completely describes the operation. For push instructions, 
this mode causes data to be added to the top of the stack and the stack pointer to 
be decremented by the size of the data. For pull instructions, data is taken from 
the top of tiie stack and the stack pointer is incremented. 

Stack Relative sr,S 

A common technique for passing parameters to a subroutine is to place the param- 
eters on the stack prior to executing the JSH or JSL instruction. As the next chapter 
will cover, this is the technique you will use when calling GS tool set functions. 
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An easy way to retrieve parameters passed on the stack, or to return parameters 
in the stack, Is to use the stack relative addressing mode. With this mode, you 
specify a one-byte numlx-r from $00 to $FF; the 65816 adds this number to the 
contents of the stack pointer to del ermine I he effective address, 

Suppose a program calls a subroutine by pushing one word of data on the stack 
, the JSR. When the subroutine- gets control, the stack looks like this: 



SP 



— > 



parameter 



return address 



SP+3 
SP+1 



To access the parameter, use the following instruction: 

LDA $03,5 

The offset from the Stack pointer is $03. because SP points to the address just below 
the JSB return address, and the return address is two bytes long. If the subroutine 
had been called with a JSL instruction, the offset would be $04 because a Ion* 
return address is three bytes bng. 

Note that if the subroutine pushes any data on the stack alter getting control, 
the offset to the parameter must be adjusted accordingly. 

Stack Relative Indirect Indexed with Y (sr,S),Y 

This addressing mode is useful if the stack contains a pointer to a data structure in 

the current data bank. By specifying a stack offset from $00 to SFF and loading the 

Y register with an offset into the data Structure, you can access any field in the data 

structure. 

The assembler format For this mode is isr.Sl.Y. The 65H\6 calculates the effective 
address by Krsl adding sr to S. It then takes the pointer stored at that address and 
adds to it the value stored in the Y regi 

One difficulty with this mode is that it docs not work with long (24-bit) address 
pointers, and these are the types of pointers passed to (.s too! set functions In this 
situation. Li is better to use the direct page indirect long indexed with Y addressing 
mode (see below). You can do this by defining a new direct page that begins at the 
base of the stack. 

Block Move srebnkdestbnk 

This addressing mode is used only by the MVN and MVP block move instructions 
The form of the operand is two bank numbers separated by a comma: the first bank 
is the bank for the source block and the second is the bank for the destination block. 
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Absolute Addressing Modes 



Absolute 


addr 


Absolute Long 


addr 


Direct Page 


dp 



The effective address lor the absolute addressing mode is the 16-bit address defined 
by the label in the operand field, The 65816 forms the effective 24- bit address by 
combining this address with the number in the program bank register. 
Here are some examples of the absolute addressing mode: 

LDA MyData 
STX TheResult 
RDL BitFlags 

In each case, the operand field contains a symbolic label for the address. 

When using the absolute addressing mode, it is very important to ensure that 
the data hank register is the same as the program bank register, at least if the labels 
refer to offsets into the program bank (the usual case). The easiest way to do this is 
to execute PHK, PLB instructions at tin- beginning of the program. 

If the data bank register is not set up properly, you must use the absolute long 
addressing mode. In this situation, the effective address is the 24-hit address spec- 
ified in the operand; the data bank register is not referenced. Most assemblers, 
including Apple 5 APW assembler, default to absolute addressing if they cannot tell 
it the address is long (24-bit) or normal (16-bit). To force absolute long addressing, 
put a > symbol in front of the address. 

II the operand is a location in direct page, you can use the direct page addressing 
mode instead of absolute or absolute long. 

Absolute Indexed Addressing Modes 

Absolute indexed with \ addr , X 

Absolute indexed with Y addr , Y 

Absolute long indexed with X absaddr T X 

Direct page indexed with X dp , X 

Direct page indexed with Y dp , Y 

These indexed addressing modes are the same as the corresponding unindexed 
addressing modes, except that the 65816 adds the contents of an index register to 
the specified address to form the effective address. Here are some examples: 



LDA 


TaskRecord J 


- T EA - 


Ta5kRecord*X 


STfl 


MyField^Y 


;EA - 


MyField-Y 


LDA 


*E1 0O0O.X 


■>EA - 


$E1 00Q0+X 


STA 


$32 ,X 


;EA = 


$32 + X 


LDX 


$16, V 


;EA = 


I1B+Y 
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Use these modes to step into the data structure beginning at the base address. The 
base address is either a 16-bit address (addr), a 2-1 -bit address (absaddr), or a direct 
page address (dp). 

Indirect Addressing Modes 

There are eight different indirect addressing modes you can use lo access a data 
structure whose address is passed to you as a parameter 

Direct page indirect ( dp ) 

Direct page indirect long [ dp ] 

Absolute indirect (addr) 

Absolute indirect long [addr ] 

Absolute indexed indirect (addr , X ) 

Direct page indexed indirect with X ( dp , X ) 

Direct page indirect indexed with Y ( dp ) , Y 
Direct page indirect long indexed with Y C dp ] , Y 

If you know the absolute position in memory of the data structure, you can use a 
direct addressing mode instead of an indirect addressing mode. 

The indirect addressing modes all involve address pointers that are two (normal) 
or three (long) bytes in length. These pointers are stored in memory with the low- 
order byte or bytes first. 

The indirect modes which use nondirect page addresses for storing the pointers 
work with JMP and JSR instructions only: 

JMP (addr) ;16-bit pointer 

JMP [addr] ;long pointer 

JMP (addr,X) ',16-bit pointer 

JSR (addr,X) ;1S-bit pointer 

For these modes, addr is the address at which the pointer to the data structure is 
stored. For (addr) and [addr] modes, this address must he in bank $00. 

The (addr.X) mode is often used to pass control to a subroutine whose address is 
in a table of subroutine addresses beginning at addr. By putting the relative position 
of the subroutine address in X, you can call the subroutine with JSR (addr,X) or 
JMP (addi\X). That is because the 65816 forms the effective address by adding the 
value in the X register to the address specified in the operand. 

For the other five indirect addressing modes, the pointer must be in a direct 
page location. The effective addresses are calculated as follows: 

( dp ) EA = the address stored at dp/dp + 1 

[ dp 3 EA = the address stored at dp/dp+l/dp + 2 

( dp ) ,Y EA = the address stored at dp/dp+1 plus Y 

36 Programming the 65816 Microprocessor 



PHD 




TSC 




TCD 




LDA 


#$8000 


LDY 


#2 


STA 


[$061 ,Y 


PLD 




RTL 





C dp ] , Y EA = the address stored ai dp/dp+ l/dp+2 plus Y 
( dp , X ) EA = the address stored at dp+X/dp + X+1 

Note: The eflectivi: addresses are addresses in the bank stored in the data bank 
register. 

Use the (dp) or [dp] or (dp,X] modes it you need to access only the first byte (8- 
bit register] or word i Mi-bit register] ol the data structure. To manipulate other 
portions ofa data structure, you must use ulpi.Y or |dpJ.Y after setting the V register 
to the appropriate value. 

The |dp],Y addressing mode is useful lor accessing data structures whose long 
pointers arc passed on the stack to a subroutine. Here is an example oJ a subroutine 
thai stores a result in bytes $20/$21 ofa data structure whose address is pushed on 
the slack before the subroutine is called with JSL: 

j 3 bytes at top of stack an entry (from JSL} 

;5ave d - p . register {adds 2 to BP) 

;Make direct page = stack pointer 
; This 15 the value to return 
-.access 2Qth byte 
; at ore the result (*0G - 2+3+1) 
;Reslore original direct page 
} (Sub called with JSL) 

Rather than remove tin- pointer From the stack and pul it in the current direct page, 
this subroutine defines a new direct page thai begins at the address stored in the 
stack pointer. Because this occurs after the PHD instruction, the direct page address 
of the stack parameter is SOB; the long return address (pushed on the stack by JSL) 
is at $O3-$05, and the copy of the direct page register is at $0l-$02. 

INTERRUPTS 

An interrupt is an electronic signal that demands the immediate attention ol the 
microprocessor. The signal can originate from either a hardware device or a pro- 
gramming instruction. The four basic types of hardware interrupts are: 



• IRQ (interrupt request) 

• NMI (nonmaskable interrupt) 

• Reset 

• Abort 
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The two types of software interrupts are: 

• BRK (break) 

• COP (co-processor) 

This section takes a look at how the 658J6 deals with interrupts. 

The IRQ Hardware Interrupt 

An IRQ hardware interrupt is an electrical signal from a peripheral device that 
activates the IRQ (interrupt request) pin on the 65816. When the 65816 senses an 
active IRQ signal, it stops executing the current program and switches to another 
program, called an interrupt handler, to deal with the source of the interrupt. When 
the handler ends, control returns to the original program and execution continues. 

It is easier for a program to deal with input devices that interrupt the system 
because there is less risk of missing incoming data. If the device does not interrupt, 
the program must periodically check its status to see if the device has data ready. 
II the program does not check often enough (perhaps because it is executing a time- 
consuming subroutine), it will get behind and lose data. 

Some of the sources of IRQ interrupts on the GS are the serial ports, the mouse, 
the keyboard, the clock, the video controller, and the Ensoniq DOC. The serial 
ports, lor example, can be programmed to generate interrupts when they receive 
data. The interrupt handler will then read the data and store it in a buffer so that 
it could be retrieved by the program when it is ready for more input. 

If you set the interrupt disable flag in the 65816 status register, the 65816 will 
ignore IRQ interrupts. You may want to do this if your program is in the middle of 
a critical timing loop or if the program is not re-entrant (capable of being called 
while it is in use) and there is a possibility the interrupt handler may call the 
program recursively. In general, interrupts should be left on at all other times. 

When an IRQ interrupt occurs, the 6.5816 takes one of two actions, depending 
on its current mode. In native mode, it pushes the program bank register, the 
am counter, and the status register on the stack. In emulation mode, only the 
program counter and the status register are pushed. Then the 65816 clears the 
decimal mode flag in the status register and sets the in term pt disable flag so that 
nothing will interrupt the interrupt-handling subroutine. Finally, the 65816 passes 
control to a vector In bank $00 associated with IRQ interrupts. As shown in table 
2-2, the position of this vector depends on the operating mode. The interrupt 
handler ultimately passes control to a user vector at $3FE/S3FF in bank $00 — that 
is r if control is nol handled internally. 

An interrupt handler must end with an RTI instruction because RTI pops the 
values pushed on the stack when interrupt processing begins. Because only the 
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Table 2-2: 65816 Interrupt Vectors 






Emulatiun Mode 


Vectors 


Native Mode 


Vectors 


$(X)FFFE/FF 


IRQ, BRK 


$<)<>! i 1:1: i:r 


IRQ 


$00FFFC/FD 


Reset 


$0OFFEA/EB 


NMI 


SOOFFFA/PB 


NMI 


$0OFFE8/E9 


Abort 


S0OFFF8/F9 


Abort 


SOOFFE6/E7 


BRK 


S00FFF4/F5 


COP 


SOOFFE4/E5 


COP 






I00FFFC/FD 


Reset 



program counter and the status register are saved on the stack, the interrupt handler 
must preserve the states of the other 65816 registers it alters,. 

The preterred way to install interrupt handlers in a ProDOS environment is to 
use the ProDOS ALLOC— INTF.RRUPT command. (See chapter 10.) In these eases 
the interrupt handler does not have to preserve registers and can end with an RTS 
(ProDOS 8) or RTL (ProDOS 16) instruction. This is because the internal ProDOS 
interrupt dispatcher takes care of saving registers and returning control properly. 

Other Hardware Interrupts 

Devices can also generate NMls (nonmaskable interrupts). The 65816 handles them 
just like IRQs except that it uses a different interrupt vector and it never ignores 
them even if the interrupt disable flag is set. A peripheral might cause an NMI if 
it has to take over the system in an emergency situation, such as an impending loss 
of power. The NMI interrupt handler in the CS eventually passes control to a user- 
installed subroutine whose address is stored at $3FC7$3FD in bank $00. 

A Reset interrupt occurs when you turn the CS on or when you press Control- 
Reset. When Reset is caused by the power turning on, the system boots the start- 
up disk. When power is turned on. Resets are handled by eventually passing control 
to the subroutine whose address is stored at S3F2/S3F3 in bank S00, but only if the 
byte at S3F4 is equal to the number generated by exclusive-ORing the number at 
$3F3 with the constant $A5. If it is not, the system is rebooted instead. 

The last type of hardware interrupt is the Abort interrupt. It is supposed to be 
generated by a hardware memory-management unit when it detects a program 
trying to access memory that is off-limits to it. On the gs, only cards installed in 
the memory expansion slot can generate Abort interrupts. 

The addresses of the vectors for NMI, Reset, and Abort interrupts are shown in 
table 2-2. 
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Software Interrupts 

You can also generate interrupt signals by executing a BRK or COP instruction 

inside a program. The 658! to such interrupt signals just as it reacts to an 

active IRQ signal, but it uses a different interrupt vector. Neither the BRK nor the 
COP instruction can be masked by the interrupt disable Sag in the -status register. 

BRK and COP have separate interrupt vectors but are handled in much the same 
way by the c.s monitor (The COP instruction was designed to pass control to a 
65816 coprocessor chip, but such a chip is not available yet) When you start up 
ProDOS 8, however, both vectors eventually pass control to the same RAM vector 
at $3FW$3F1 in bank $00. This vector points to a monitor subroutine that displays 
the contents of the 65816 registers. 

BRK and COP are both two-byte Instructions even though the second byte lias 
no particular meaning. The BRK or COP handler you install can examine the second 
byte and interpret it any way it wishes. It is essentially a parameter that is passed 

to the handler. 

Note that in emulation mode, BRK and IRQ interrupts share the same interrupt 
vector. To distinguish between them, the system examines the break bit in the 
status register; if it is 1, the interrupt was caused by a BRK instruction and the t;s 
monitor passes control to the vector stored at $3F0/$3Fl instead of to that at $3FE/ 
$3FF. 

CREATING PROGRAMS WITH THE APPLE lies 
PROGRAMMER'S WORKSHOP 

The Apple lies Programmer's Workshop i .APWi contains all the programs and 
support files you will need to develop 65816 assembly language programs on the 
GS. There are four key module 

■ The shell (command interpreter) 

• The text editor 

• The linker 

• The 65816 assembler 

By acquiring APW-eoinpatible compilers, you can also use APW to develop programs 
written in higher-level languages like C and Pascal. 

To begin writing a 65816 program, start up APW and ensure that the active 
language is 65816 assembly by entering the ASM65816 command from the shell, 
(This language is the initial default, so yon can skip this step if you have not switched 
to another language.) You must choose the correct language because the assembler 
will not deal with source files treated by the editor when another language is active 
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The next step is to invoke the editor with the command: 

EDIT pathname 

where "pathname" represents the name of an existing source file or the name of the 
new file you want to create. 

Now the hard part: you must write your application! To do this requires an 
intimate knowledge of the syntactical requirements of the assembler. 

Source Code Format 

Lines of assembly language source code arc made up of four fields, separated by 
one or more spaces, in the following order: 

• Label field {usually optional] 

• Instruction field 

• Operand field 

• Comment field (optional! 

The major exceptions are comment lines, which begin with ":"', "*" or ""!" symbols. 
You can put whatever you like in these lines because they are ignored by the 
assembler. 

The Label Field. The label field optionally contains a symbolic label, usually for 
marking a position within the program to which other parts of the program can 
refer. Labels can also be associated with numeric constants with the EQU and 
CEQU assembler directives (see below)* 

A label must begin with an alphabetic character (A to Z) or an underscore ( J, 

Subsequent characters can be alphabetic (A to Z), numeric (0 to 9),- the tilde 
the underscore ( — ). The maximum length is 255 characters. The assembler usually 
ignores the case ol alphabetic characters, but you can make it case-sensitive with 
the CASE ON directive. 

The Instruction Field. The instruction field n iins the 65816 instruction or an 
assembler directive. Directives are commands to the assembler, not 65816 instruc- 
tions. They tell the assembler to do such things as set or clear internal status Bags, 
define symbols, allocate data storage areas, save object code to disk, and create 
macros. 

If the label field contains an entry, the instruction field must not be blank: if no 
instruction is wanted, use the ANOP (assembler no operation) directive. Unlike 
some assemblers, the 65816 assembler does not allow you lo define lines that contain 
only a label. 
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The Operand Field. The operand field contains the addressing mode for the 
instruction or a parameter for the assembler directive. It may be blank if the 
instruction or directive 1 requires no explicit operand, 

The Comment Field. The comment field, which begins with a : symbol, can contain 
any explanatory test you like. Use it to document your program code. 

The source code shell for a typical 65816 program looks something like this: 

KEEP MyProgram ;Name of object code file 

MCOPY Macros. Mac ; Name of macro file 

CodeSegl START ;5tart of main code segment 

USING GlobalData ;It uses GlobalData data 

Private NOP '."Private" is a local label 

<put program code 

here> 
MySub ENTRY ;A global entry point 

<fnore program code 

hero 

END 
Code5eg2 START ^Another code segment 

USING GlobalData ; I t can use GlobalData tool 

JSR CodeSegl ;You can access through 

JSR MySub ^global entry points. 

JSR Private .Error!!! But not local ones! 

<code for another 

segment here 

END 

CDPy OtherCode.Asm ;Name of other file to include 
GlobalData DATA 

<put data allocation 

statements h e r e > 

END 

the "KEEP pathname" directive saves to disk the object code generated by the 
assembler under names of the form "pathname. ROOT" (for the first code segment 
in the program] and pathname. A" (for all oilier segments, if any . The ProDOS file 
type code for tlie.se files is SB 1 and the standard mnemonic is OBJ. The KEEP 
directive must appear before the first START directive. 

"MCOPY pathname" tells the assembler the name of the file in which macros 
referred to in the source file are defined. Macros will be described in greater detail 
below. 

COPTl pathname tells the assembler to load the specified source file and assem- 
ble its statements. On completion, assembly continues with the next line in the 
main file. Use it to include standard source code fragments in your main source 
program file. 

All 65816 instructions in a program source file must fall inside one or more code 
Segments defined by START and END directives. START marks the beginning of a 
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code segment and must be associated with a label that identifies the subroutine or 
main program in the segment, END marks the end of the segment. 

A single source file may contain any number of code segments. The advantage 
of partitioning a program into several segments is that aJI labels defined inside the 
segment are local to the segment. This means that the same labels can be reused 
in another segment without generating an assembly error. This is especially con- 
venient if you are developing extremely targe programs in which the risk of symbol 
duplication is great. 

The label used with the START directive is global, which means that it cannot 
be used as a label anywhere else in the program. It identifies the primary entry 
point to the subroutine contained in the segment. You can use the ENTRY directive 
to define other global entry points into the subroutine, if you wish. Like START. 
ENTRY requires a label. 

You can define program segments that contain only data (no instructions! with 
the DATA directive, A data segment must end with the END directive. 

U you might expect, the labels inside a data segment are local to that segment. 
although the name of the data segment is global. You can. however, associate a data 
segment with a code segment so that the data segments labels, in effect, become 
local to the code segment as well. To do this, use the "USING DataSeg.V 
direetive. A data segment may be used by any code segment in this way. 

Local and Global Labels 

You will probably want to associate symbolic labels to numeric constants to make 
your source code easier to understand and to debug. You can do this with the EQU 
(equate) or CEQU (global equate) directives, 
Here arc some examples: 

True GEQU $8000 ; takes effect throughout program 

BitPos EQU 3 ;takes effect in current segment 

CEQU creates a global constant — one that takes effect in even code and data 
segment in the source file The same label may not be redefined elsewhere in the 
program. 

EQU creates a local constant, which takes effect milv inside the segment in which 
the constant was defined. EQU labels can be redefined in other segments. If an 
EQU label has the same name as u CEQU label the EQU label takes precedence. 

ProDOS 16 Entry Conditions 

Just before ProDOS 16 passes control to an application, it puts the system into a 
standard operating state: 

• full native mode (»i=0, ,*— 0, e=0) 

• the X and Y registers are zero 
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• the A register contains the ID tag lor the program 

• shadowing of the text screen is cm 

* shadowing of the graphics area is off 

* I/O shadowing and language card operation is on 

(The concepts of ID tags and shadowing will be explained in chapter 4.) 

In addition, ProDOS lfi reserves a space in hank S00 for use as a direct page and 
stack area. This is normally a IK space, hut can he changed using advanced assembly/ 
linking techniques. On entry to the program, the direct page register contains the 
address of the first hyte in this space and the stack pointer points to the last byte 
in the space. 

Mode Considerations 

After ProDOS 16 loads an executable application into memory, it puts the 65816 
into full native mode with LB-hit A, X, and Y registers; it then passes control to the 
beginning of the first rode segment, This means the program does not have to 
change modes with XCE or REP if it needs to run in full native mode. 

The assembler must he told of any changes in the size of the accumulator and 
index registers so that it can assemble the following instructions correctly: 

LDA 'immediate SBC 'immediate 

LDX 'immediate EDR 'immediate 

LDY 'immediate BIT 'immediate 

ADC 'immediate ORA 'immediate 
AMD 'immediate 

The assembler Initially assumes settings of LONGA ON (16-bit accumulator) and 
LONGI ON (16-bit index registers) LONGA and LONG] are directives that appear 
in the instruction held of a line of source code. If the directive is set to OFF, the 
assembler considers the corresponding register to he 8 bits in size. 

Any time you change register sizes using REP or SEP, you must also tell the 
assembler by adjusting LONGA and LONGI to the appropriate values. 

Numbering Systems 

The APW assembler understands many different numbering systems. The ones you 
will use most often are decimal, hexadecimal, and binary. To indicate which system 
you are using, place a special identification character in front of the number: 
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$ Hexadecimal number (for example, $FFAD) 
% Binary number (for example, %O1100111) 

No special character is needed for a decimal number, because decimal is the default 
numbering system. 

Isolating the Wends in a Long Address 

You often need to load a register with the low- or high-order word of a particular 
address. Loading the low-order portion is easy: 

LDA 'Address ;Load address (low) 

Because the A register (or X, V) is 16 hits in size, the upper 8 bits of Address are 
ignored. To load the high-order portion, you must append "|-I6" to the address 
operand (which means 'shift right l>> lb bits") or precede it with "" as shown in 
(he lol lowing examples: 

LDA fAddres 5 - 1 6 ;Load high-order word 

LDA '"Address ; ( a 1 1 erna 1 1 ve melhod) 

In both eases, the hank portion of (lie 24-bit address is the low-order 8 bits of the 
accumulator. The top S bits are zero. 

For PEA operations, do not include the "#" because the addressing mode is 
absolute, not immediate. To push the two words of an address on the stack, do this: 

PEA Addres5|-1G ;Push address high 

PEA Address -.Push address low 

(The Al'W assembler does nol allow an "Address operand for PEA instructions.) 
This is the preferred technique lor pushing address pointers because it does nol 
require using a 65816 register. 

Forcing Addressing Modes 

When \imi specify an address as an operand, the APW assembler normally considers 

il to he an ahsolute address, as opposed to a long absolute or direct page address, 
and assembles the instruction accordingly. Exceptions are symbolic addresses de- 
fined by EQl) or GEQU directives; here, \l J \V is able to determine tin- appropriate 
addressing mode. 

Using absolute addresses may or may not he appropriate, depending on the state 
ol the data bank register. 11 the symbol for the address identifies a location inside 
the program itself, absolute addressing is improper ii the data bank register is not 
the same as the program hank register. In this situation you can either make the 
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two banks the- same (with Pllk. l J LB instructions) or force absolute long addressing 
by preceding the name of the address label with the > symbol. 

For example, to load the A register with whatever is stored at My Address, execute 
the following code: 

LDA JflyLabel ;Uae absolute long addressing 

This forces the 65816 to read the value from the program bonk as intended. 

Similarly, you can force direct page addressing with the "<" symbol and absolute 
addressing with the "|" symbol: 

LDA <MyAddress ;Force direct page addressing 

LDA IMyAddress ;Force absolute addressing 

You would use these only if the assembler would normally assemble these instruc- 
tions using a different addressing mode. 

Data Allocation Directives 

You will use data allocation directives to reserve space lor data inside the program, 
or (or storing specific values inside the program. To reserve space, use the DS 
directive; 

DS 45 i Reserve 45 bytes 

The operand of the directive is the number of bytes to reserve. The line containing 
i DS directive may contain a label. 

To store specific values in the object code, use the DC {define constant) directive 
instead of DS. It is of the form: 

label DC constant_def 

where constant_def defines the type of data to be stored. Hen are examples of the 
most common constant definitions: 

11 22* One byte 

12 396 Two bytes (one word) 
['298* Two bytes (one. \M>n.li 

i i $8000' Four bytes (long word) 

I1FE12SA Hexadecimal digits 

B1OO110' Binary digits 

CText String" Sequence of characters 

The It definition ix is an integer from 1 to 8) T stores multiple bytes in memory, low- 
order bytes first. This is the order expected by 65816 instructions. If A" is omitted. 
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two-byte words are stored. The number specified ran be in binary, decimal, or 
hexadecimal form. 

The H definition stores successive pairs of hexadecimal digits in successive mem- 
ory bytes, | An> spaces in the digit string an- ignored,) If an odd number of digits is 
specified, the low-order four bits of the last byte will be set to 0. 

The B definition stores successive fin nips of right binary digits in successive 
memory bytes, ignoring any spaces. If the number of digits specified is not an even 
multiple of eight, the last byte is padded on the right with bits. 

The C definition stores the ASCII codes for the specified character string in 
memory. The MSB ON and MSB OFF directives control the setting of the high bit 
for these string constants, The default is MSB OFF, meaning that bit 7 of each byte 
is 0. Use MSB ON if you wish to force bit 7 hi L 

Several constant definitions can be included on one line by separating them with 
commas, For example, the command: 

DC 11 '0» , 12'SFDDA 1 ,H'AE« 

stores the bytes $00 SDA SFD $AE in the object code at assembly time, 

To define several items of the same general type, put the items, separated by 
commas, inside the single quote marks of the constant definition string: 

DC I2'34,$A32i ,16' ^Stored as 22 00 21 A3 ?0 00 

Another nice feature of the DC directive is that it gives you the ability to put a 
repeat count in front d' j constant definition. Fur example, to generate six copies 
oi $FDED, use the following command; 

DC 6I»$FDED' 

Notice that in this example the "2" after the "I" was omitted. As indicated above, 
the assembler assumes it is dealing with words in this situation. 

Listing Directives 

The APW assembler supports several directives thai affect the output of the assembly 
process: 

• LIST (display obj 

• SYMBOL (display symbol table) 

• ABSADDR (display code addresses) 
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• INSTIMK (display instruction cycle times) 

• GF.N (display macro expansions) 

Thee directives can either be ON or OFF; put the ON/OFF status indicator id the 
operand field- The defaults for all these directives is OFF. 

Creating the Macro File 

.X ,„„, is M assembler command that expands into a series of 65816 instructions 
tr Ambler di^ttvesjdurmg the ^mblyp^s. By ^ng^ffl^^ed 

short code fragments to a macro command, you can develop programs much more 
rapidly and make then much ...ore readable at the same time, 

' As the next chapter will discuss, the cs supports many tool set firnctmns that jw 
invoke by loading the X register with an in number and then doing a JSL , to 
KWm ' You *'«* have to memorize these ID numbers, because Apple prmados 
with Al'W , set of macro definitions that associates easy-to-remember nanus with 

each of the L.DX/JSL junction calls- 

„„ can define powerful macros for use with the Al'W assembler. For a compre- 
hensive description of how lo create macros, sec the AFW Awmifa Rfrencv. To 
I!:.! Iteel for how to create macros, look at this one, called PusnAddr, which pushes 

the address of a program or data area on the stack: 



MACRO 



& lab 

.lab 



■Start macro definition 
PushAddr iaddr .Name of macro, parameters 
PEA 4addr|-l6 ;Body of macro 
PEA iaddr ".Body of macro 

; End of macro 



MEND 
To invoke this macro, you would place a line such as; 

MyLabel PushAddr MyRecord 

in y0U r program source code When the assembler expands the macro into 65816 
s Zions i. replaces &lab with MyLabel and fcaddr with MyRecord wherever 
CJSi in the body of the macro definition. For the above example, tms means 
ihe following statements would be generated: 

MyLabel PEA MyRecord|-16 

PEA MyRecord 

Tie MACRO directive marks the beginning of the macro definition. The next line 

Lntams the name of th aero in the Mrrtta WLB ^oddftnes ggfiS* 

yon can pass to the macro; their names begin with the & symbol For PushVldr 
on" pa, a meter is a label appearing in the label field (ftUft the other is an addre» 
appearmg in the operand Held (taddr). Multiple oonbbel parameters appear m the 
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operand field of a macro, separated by commas, The MEND directive marks the 
end of the macro definition. 

With conditional assembly techniques you can define macros whose behavior 
depends on many things, such as whether the parameters you specify are immediate 
values or addresses. Examples of macros like this are given in listing 2-1. (These 
macros are ideal for passing parameters to tool set functions and for retrieving 
results, as will be shown in the next chapter.) Consult the APW Assembler Reference 
for a detailed explanation of how to use these advanced macro features. 

Almost every program you write for the cs will use macros, primarily the ones 
that assign symbolic names to tool set functions. The macros must appear in a 
separate file that is referred to by an '. VI COPY pathname" directive in the primary 
source code file, 

APW comes with a program called MACGEN that you can use to extract the 
macros needed by a program from the standard APW macro files and to put them 
in a custom macro file. For example, suppose your source program is called WIN- 
DOWS, ASM and it uses macros defined in M18.QUICKDRAW and 
M 16. WIN DOW. To place all the macros used by the program in a file called 
WINDOWS. MAC] (the file named in the program's MCOPY command), type in 
this command: 

MACGEN WINDOWS. ASM WINDOWS. MAC Ml 6. QUICKDRAW M16. WINDOW 

MACGEN scans the source file (the first file named) for macro references and places 
their definitions in the macro file (the second file named). It searches the third and 
fourth files (and an\ r more you might specify on the command line) for these macro 
definitions. If not all macros are found r MACGEN asks you to enter the name oi 
another macro file to search; it keeps asking until it finds every definition. 

Quite often you will create a macro Hie. then change the program slightly so that 
it uses a few new macros. To add just the new macros to the existing program macro 
file, specify the program macro file as one of the MACGEN search files: 

MACGEN WINDOWS. ASM WINDOWS. MAC WINDOWS. MAC M16. WINDOW 

By doing this, you avoid having to Specify the names of all the system macro files 
containing the macros you already have in the program macro Hie. 

Creating an Application with APW 

The APW assembler processes a 6.5816 source code file and converts it into an 
object code file. The resultant object code file is not the executable program, 
however. Instead, it contains code modules that the APW linker must process first. 
It is the linker that creates the executable ProDOS 16 load file. A load file contains 
the program code and a header that tells the System Loader (the tool set responsible 
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for loading programs into memory) how to make the program run properly at the 
load address. 

Object code files produced by the assembler are in a special language-indepen- 
dent format defined by Apple. High-level language compilers that work in the APW 
environment (notably C and Pascal} use this same format. The linker dues not care 
which language created the object code, so you can develop portions of a program 
in different languages, then combine them with the linker to create the final appli- 
cation. 

The APW command for assembling and linking simple applications in one step 
is ASML. If you need to perform special linking operations (such as including code 
libraries), you have to separately process a linker control file written in the LINKED 
language instead; for information on the LINKED language, see the APW Assemble r 
Refer t > 

After assembling and linking, APW creates an executable ProDOS 16 load file 
with a file type code of 365 (the standard mnemonic is EXE). This program can be 
run from the APW shell simply by typing in its name. When it ends (with an RTL 
instruction or a ProDOS 16 QUIT command), control returns to the shell. 

Once you have thoroughly debugged the program, you should change its file 
type code to $B3 (the mnemonic is $16) so that ProDOS 16 will recognize it as an 
application. Do this with the APW F1LETYPE command; 

FILETYPE pathname SB3 

where SB3 is the new file type code. You can specify the S16 mnemonic instead of 
the hexadecimal code, if you wish. 

An S16 program can be executed from the APW shell, but it will crash the system 
if ft ends with an RTL instruction. This is because the shell removes itself from the 
system when it passes control to ihe program, so it will not be there on return. 
(With EXE programs the shell stays intact.) The moral is to always end a program 
with a ProDOS QUIT command. This command is described in chapter 10. 

REFERENCE SECTION 

Table R2-1: The Complete a5816 Instruction Set 



Effect on Flags 

instruction Addressing NV-BDIZC e=l 

Af nemom'c Operation Opcode Mode C ycles NVmxDIZC e=Q 

ADC add to accumulator .$69 immediate 2 1 NV....ZC 

4 l 
5' 



add to accumulator $69 


#ini 


with carry * fi ^ 


addr 


$6F 


long 


$65 


dp 



3' 
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Mnemonic 


Instruction 

Operation 


Opcode 


Addressing 
Made 


Cycles 


Effect on Flags 
NV-BDIZC e=i 
NVmxDIZCe-0 






$71 


(dp),Y 


5 W 








$77 


[dp],Y 


6 1 








$61 


(dp,X) 


6' 








$75 


dp.X 


4 ; 








S7D 


uddr.X 


4' ' 








S7F 


long.X 


5 1 








S79 


addr.Y 


4' ' 








872 


(dp) 


.=>' 










Idp] 


6 ] 








$63 


sr f S 


i 1 








$73 


(si S 1 


7 1 




AND 


Uncivil] AND with 


$29 


#irn mediate 


■2 l 


N. . . . .Z. 




accumulator 


S2D 


addr 


i- 








$2F 


long 


5' 








$25 


dp 


3 1 








$31 


(dp),Y 


5 W 








$37 


[dp).Y 


6 1 








$21 


(dp.X) 


6 1 








$35 


dp.X 


4 1 








$3D 


addr,X 


4 13 








$3F 


long,X 


5 J 








$39 


addr.Y 


4 M 








$32 


<dp> 


5 J 








$27 


[dp] 


6" 
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Ejfjfrcf on /'7«#s 




Instruction 




Addressing 




NV-BDIZC e= 1 


Mnemonic 


Operation 


Opcode 


Mode 


Cycles 


N'VmxDIZC e=0 






S23 


sr,S 


4 1 








133 


(sr,S),Y 






ASL 


arithmetic shift left 


SOK 


addr 


6 2 


N. . . . .ZC 






$06 


dp 


5 a 








SOA 


A 


2 








$16 


dp.X 


6 3 








$1E 


addr.X 


- 




BCC 


branch on carry 
clear (C=0) 


$90 


rel 


2 4,5 




BCS 


branch on carry set 

(C=l) 


$B0 


rel 


2 <a 




BEQ 


branch on equal 
(Z=l) 


$F0 


rel 


2 4S 




BIT 


logically AND the 


S89 


# immediate 


2' 


NV. . . .Z. 




accumulator with 
the operand; 


S2C 


addr 


4' 






transfer high-order 


S24 


dp 


3* 






hits tn \ and V 
(but not if 


$34 


dp,X 


4 1 






# immediate) 


S3( : 


addr,X 


4 13 




BMI 


branch on minus 


$30 


rel 


2 <s 




BNE 


branch on not 

equal 

(2-0) 


$D0 


rel 


2 45 




BPL 


branch on plus 
(N=0) 


$10 


rel 


a* 5 
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Effect on Flags 
Instruction Addressing NV-BD1ZC <?=1 

Mnemonic Operation Opcode Mode Cycles NVmxDIZC e=0 

BRA branch relative $80 rel S 

always 

BRK break interrupt $00 {stack} 7* ....01.. 

BRL branch relative §82 longrel 4 

long 

BVC branch on overflow $50 rel 2* ,s ...,,,,, 

clear (V=0) 

BVS branch on overflow $70 rel 2 4,5 ........ 

set (V=l) 

CLC clear carry flag SIS {implied} 2 

CLD clear decimal flag $DS {implied} 2 . . . . . ♦ . 

CLI clear IRQ disable $58 {implied} 2 . . 

flag 

CLV dear overflow flag $B8 {implied} 2 .0 

CMP compare with $C9 # immediate 2 1 N,,,,. ZC 

accumulator .„ n . . , 

$CD addr 4 1 

$CF long 5' 

$C5 dp 3 1 

$D1 (dp.U 5 M 

$D7 [dp] T Y 6 1 

$CI (dp 6 1 

$D5 dp.X 4' 

$DD addr.X 4 l ;i 

WF long,X 5' 
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Effect on Flags 




Instruction 




Addressing 




NV-BDIZCe=l 


Mnemonic 


Operation 


Opcode 


Mode 


Cycles 


NVmxDlZC e=0 




8U9 


addr.Y 


4 M 








SD2 


(dp) 


r V 








SC7 


Ldp] 


<i' 








$C3 


sr,S 


! l 








$D3 


(sr,S),Y 


r 




COP 


co-processor 
interrupt 


S02 


{stack} 


i 


. . . .01 , . 


CPX 


compare with X 


SEO 


■# immediate 


2' 


N ZC 






SEC 


uddr 


3 7 








SE4 


dp 


2 7 




CPY 


compare with Y 


SCO 


#im mediate 


2 T 


N ZC 






ICC 


atldr 


r 








8C4 


dp 


3 7 




DEC 


decrement 


$CE 


addr 


e 2 


N Z. 






SC6 


dp 


_ i 








S3A 


A 


2 








SD6 


dp,X 


6 a 








IDE 


addi\X 


_ - 
i 




DEX 


decrement X 


$CA 


{implied} 


2 


N Z. 


DEY 


decrement Y 


$88 


{implied} 


2 


N. ... .Z. 


EOK 


exclusive OR with 


S49 


#immediate 


2 l 


i" . • ■ • • £. • 




accumulator 


S4D 


addr 


4 ] 








S4K 


long 


rV 
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Mne?nunic 


Instruction 
Operation 


Opt ode 


Addressing 
Mode 


Cycles 


Effect on Flags 
NV-BDlZCe=l 

NVmxDIZCe=0 






$45 


dp 


3 J 










$51 


(dp).Y 


v 










$57 


[dp],Y 


b 1 










$41 


(dp.X) 


6' 










$55 


dp.X 


i 1 










$5D 


addr.X 


4 L3 










$5F 


1ong T X 


5 ] 










$59 


addr.Y 


4' ■' 










S52 


(dp. 


5' 










$47 


[<w 


w 










$43 


sr,S 


4' 










$53 


(sr,S),Y 


-i 






INC 


increment 


$EE 
8E6 
SI A 

$F6 
$FE 


addr 

dp 
A 

dp.X 
addr.X 


6 2 
5 s 

2 

6 a 

7* 


N. 


Z . 


[NX 


increment X 


$E8 


{tin plied} 


2 


N. 


Z. 


INY 


increment Y 


$C8 


{implied} 


2 


N. 


z. 


JMP 


j in rip 


84C 
$6C 


addr 

(addr) 


3 

5 
















$7C 


(addr,X) 


<i 
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Effect on Flags 

Instruction Addressing NV-BDIZC e= L 

Mnemonic Operation Opcode Mode Cycles NVmxDIZC e=0 

JML jump long S5C long 4 ........ 

SDC [addr] 6 ........ 

JSL jump to long $22 long 8 , * 

subroutine 

JSR jump to subroutine $20 addr 6 . 

$FC (addr.X) 8 

LDA bad the SA9 immediate 2 1 N Z. 

accumulator SAD ^ 4 > 

SAF long 5 1 

$A5 dp 3 1 

$B1 (dp),Y 5 13 

$B7 fdp],Y 6 l 

?A1 (dp,X) 6' 

$BS dp,X 5 1 

SBD addr.X 5 1,a 

SBF long,X 6' 

$B9 addr.Y 4 1 ' 3 

$B2 (dp) 5' 

[dp] 6 l 

sr,S 4 l 

$B3 (si\S),¥ 7 1 

LDX load the X register $A2 immediate 2 7 N ..... 2 . 

|AE addr 4 7 

SA6 dp 3 7 
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Mnemonic 


Instruction 
Operation 


Opcode 


Addressing 
Mode 


f i/( !es 


Effect on Flags 
NV-BDIZC<?=1 
NVmxDIZC e=0 






$B6 


dp,Y 


4 7 








$BE 


addr,Y 


4 ' 




LDY 


load the V register 


$A0 


#immediate 


2 7 


N 2 - 






SAC 


addr 


4 7 








$A4 


dp 


3 7 








$B4 


dp.X 


4 : 








she 


addr.X 


! 




LSR 


logical shift right 


$-JE 


addr 


6 2 


zc 






$46 


dp 


S 2 








S4A 


A 


2 








$56 


dp.X 


6 2 








$5E 


addr.X 


7 2 




MVN 


move* block 
backward 


$.54 


src.dcsi 


i 




MVP 


move block 
forward 


$4-1 


src.de st 


i 




NOP 


no operation 


SEA 


{implied}' 


2 
2' 




ORA 


logical OR with 


$09 


# immediate 


N Z. 




accumulator 


SOD 


addr 


r 








$0F 


long 


5' 








$05 


dp 


3 1 








$11 


(dp).Y 


5 1 - 1 








$17 


HA* 


B 1 








SOI 


(dp.X) 


IV 
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Mnemonic 


Instruction 

Operation 


Opcode 


Addressing 

Mode 


Cycles 


Effect on Flags 
NV-BDIZC t?=l 
WmxDIZC t-0 






sis 


dp,X 


4 1 








$1D 


addr.X 


V 








$1F 


long,X 


5 1 








$19 


luidr.Y 


4 1 ' 








$12 


(dp) 


5' 








.$07 


[dp] 


6 1 








|03 


sr.S 


4 1 








$13 


(sr,S),Y 


-i 
i 




PEA 


push effective 
address 


|F4 


addr 


5 




PE1 


push effective 
address indirect 


$D4 


(dp) 


ft 




PER 


push effective 
address relative 


$62 


rel 


6 




PHA 


push the 
accumulator 


$48 


{ -stack! 


3 l 


........ 


PHB 


push data bank 
register 


$8B 


|st nek} 


3 




PHD 


push direct page 
register 


SOB 


{stack} 


4 




PHK 


push program bank 

register 


S4B 


{stack} 


3 




PHP 


push status 
register 


$08 


{stack} 


3 




PHX 


push the X register 


SDA 


{stack} 


:v 
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Mnemonic 


Instruction 
Operation 


Opcode 


Addressing 
Mode 


Cycles 


Effect on Flags 
NV-BDlZCe=l 
NVmxDIZC e=0 


PHY 


push the Y register 


$5A 


{stack} 


3' 












PLA 


pull the 
accumulate): 


$68 


{stack] 


4 1 


N. . . 


. .Z. 


PLB 


pull data bank 
register 


SAB 


{stack} 


4 


N, . . 


. ,Z, 


PI U 


pull direct page 
register 


$2B 


{stack} 


5 


N. . . 


. .z. 


PLP 


pull status register 


$28 


{stack} 


4 


NVmx 


DIZC 


PLX 


pull the X register 


SFA 


{stack} 


4 7 


N. . , 


. .Z. 


PLY 


pull the Y register 


$7A 


{stack} 


4 7 


N. * . 


. .z. 


REP 


reset status bits 


$C2 


# immediate 


3 


NVmx 


DIZC 


ROL 


rotate left 


$2E 

$26 

S2A 
$36 
$3E 


addr 
dp 
\ 

dp.X 
addr, X 


5 2 

2 

6 2 


N. . . 


. .zc 


ROR 


rotate right 


$6E 
$66 
$6A 
$76 
S7F 


addr 
dp 

A 

dp,X 
addr,X 


6 2 
5 2 
2 
6* 


N. . . 


,zc 


RTJ 


return from 
interrupt 


$40 


{stack} 


6* 


NVm> 


DIZC 
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Mnemonic 


Instruction 
Operation 


Opcode 


Addressing 
Mode 


Cycles 


Effect on Flags 
NV-BDIZC <?=1 
NVmxDIZC e=0 


RTL 


return from 
subroutine 

long 


$6B 


{stack} 


6 




RTS 


return from 
subroutine 


$60 


{stack} . 


6 




SBC 


subtract from 


$E9 


#immediate 


2 1 


NV. . . .ZC 




accumulator with 
carry 


SED 
SEF 


addr 
long 


4' 

5 1 








$E5 


dp 


3" 








$F1 


(dp),Y 


5 1 ' 3 








$F7 


[dp],Y 


6 1 








$E1 


<dp,X) 


6 1 








$F5 


dp,X 


4 1 








$FD 


addr.X 


4 M 








$FF 


long,X 


5 1 








$F9 


addr.Y 


4 « 








$F2 


(dp) 


5 1 








SE7 


IdpJ 


6' 








$E3 


sr.S 


4' 








SF3 


(sr,S),Y 


7 : 




SEC 


set carry flag 


$38 


{implied} 


2 


... 1 


SED 


set decimal flag 


$F8 


{implied} 


2 


1 . . . 


SEI 


set IRQ disable 
flag 


$78 


{implied} 


2 


1 . , 
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Effect on Flags 




Instruction 




Addressing 




W-BDIZC c=\ 


Mnemonic 


Operation 


Opcode 


Mode 


Cycles 


NVmxDIZC ?=0 


SEP 


M't status bits 


SE2 


#im mediate 


3 


NVmxDIZC 


STA 


store the 


88D 


addr 


4 5 






accumulator 


SSF 


long 


5' 








$85 


dp 


3 1 








$91 


(dp),Y 


gl.3 








$97 


[dpi* 


6 1 








m 


(dp.X) 


6' 








$95 


dp,X 


4 1 








$9D 


addr.X 


5 ,a 








$9F 


long.X 


5 








$99 


addr.Y 


5 ,a 








$92 


(dp) 


5 








$87 


[dp] 


6 1 








$83 


*r T S 


I 1 








$93 


(sr,S),Y 


-i 




STP 


stop the processor 


$DB 


{implied} 


3 




STX 


store the X 


$8E 


addr 


r 






register 


$86 


dp 


3 7 








$96 


dp,Y 


4 7 




STY 


store the V register 


$8C 


addr 


4 7 








$84 


dp 


3 7 








$94 


dp,X 


■r 
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Mnemonic 


Instruction 
Operation 


( Opcode 


Addressing 
Mode 


Cycles 


Effect on Ffu&s 
NV-BDtZCe 1 
NVnvvDIZC e=0 


STZ 


store 


$9C 
$64 

$74 
$9E 


addr 
dp 
dp.X 
addr,X 


4 l 
.3' 
A 
5' 










TAX 


transfer A to X 


SAA 


{implied} 


2 


N. 


2. 


TAY 


transfer A to Y 


$A8 


{implied} 


2 


N. 


. . . .Z. 


TCD 


transfer C to D 


S5B 


{implied} 


2 


N. 


Z . 


TCS 


transfer C to slack 
pointer 


SIB 


{implied} 


2 










TDC 


transfer D to C 


$7B 


(implied) 


■2 


N. 


. .Z. 


TRB 


test and reset hits 


$ic: 

$14 


addi 

dp 


6 a 

5 2 




, . .z. 


TSB 


test and set hits 


SOC 
$04 


addr 

dp 


6 2 
5* 




. . . .z. 


TSC 


transfer stack 
pointer to < • 


$3B 


{implied} 


2 


H. 


. . .z. 


TSX 


transfer stack 
pointer to X 


8BA 


{implied} 


2 


N. 


. . . .z. 


TXA 


transfer X to A 


*.SA 


[implied] 


2 


N. 


z. 


TXS 


transfer X to stack 
por 


$9A 


{implied} 


2 




...... 


TXY 


transfer X to Y 


S9B 


{implied} 


2 


N. 


. . . . z . 
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Mnemonic 


Instruction 
Operation 


Opcode 


Addressing 

Mode ( tjdes 


Effect on Flans 
NY'-BDlZCc=l 
NVmxDIZC e=0 


TYA 


transfer Y to A 


$98 


{implied} 


2 


N. Z. 


TYX 


transfer Y to X 


$BB 


[implied} 


2 


N ..... Z . 


WAI 


wait for interrupt 


$CB 


{implied} 


2 




WDM 


•jivsrrved opcode'} 


HS 


{implied} 


2 




X8A 


exchange B and A 


SEB 


lied} 


3 


N Z. 


XCE b 


exchange carry (tnd 
emulation status 
bits 


5FB 


{implied} 


2 


C 


Notes on Cycle Times , 

Far all instructions Involving direct page, add 1 cycl 

non-21 

1 Add ! cycle ifro-Q. 

- Add 2 cycles U r»-fc 

1 Add 1 cycle if indexing across i bank boundary. 

1 Add l cyde i< liir branch is taken* 


! il the low -order byte of the 

5 Add 1 cycle if c=l anc 
across a page boundary. 

* Add 1 cycle ife=0. 

' Add I cycle if r=0, 
7 cycles per byte moved 


direct pace register is 
1 the branch in taken 


Other Notes: 

In the "Effect on Flags'* column, 1 means the flat; is 

a letter means that the flan change:-, depending on tl 

* In emulation mode, the B bit is set to 1 after a 

BRK instruction. 


alwa) s set, 
e result of the 


neans the Hag is always cleared, and 
operation. 

iflects the state of the t flag. 



Reference Section 



Listing 2-1: Useful Macros For Program Development 



PuahWord Value 
PushWord 'Value 

This macro pushes a word on the stack. If an 
address is specified ("Value"), this is done with 
LDA, PHA instructions. If an immediate number 
is specified ("'Value' 1 }, the number is put 
on the stack with a PEA instruction, 

MACRO 
ILAB PushWord SValue 



LCLC 4CHAR 
*CHAR AMID «Value r 1,1 *,Get 1st character 
AIF "SCHAR"-"'", . IMMEDIATE 

*LAB LDfl SValue 
PHA 

MEXIT 

. IMMEDIATE 

4CHAR AMID iValue, 2,100 

ILAB PEA iCHAR 

MEND 



PushLong Value 
PushLong 'Value 

This macro pushes a long word on the stack, If an 
address is specified ("Value"), this is done with 
LDA, PHA, LDA, PHA instructions. If an immediate 
number is specified ("'Value"), the number is put 
on the stack with two PEA instructions. 

MACRO 
*lab PUSHLONG Walue 

LCLC 4CHAR 
*CHAR AMID *Value,1,1 -,Get 1st character 
AIF "4CHAR"-"'", , IMMEDIATE 
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(lab 



LDA 


(Value+2 


PHA 




LDA 


* Value 


PHA 





HEX IT 

.IMMEDIATE 

iCHAR AMID 



ilab 



(Value, 2,1 00 



DC 


11 


$F4' 




;PEA opcode 


DC 


12 


((CHAR)/ 


-16' 


; Address high 


DC 


11 


*F4' 




;PEA opcode 


DC 


12 


(CHAR' 




;Address low 



MEND 



1 PuahPtr Label 

i 

5 Push a four byte pointer on the stack. 





MACRO 








4iab 


PushPtr 


(Label 






ilab 


DC 


11 »1F4" 




PEA opcode 




DC 


12' { (Label )| 


-16' 


Address h i q h 




DC 


11 ' *F4' 




PEA opcode 




DC 


I2»(Label » 




Address low 




MEND 









5 PopLong DataAddr 

; Th j 5 macro pops a long word off the stack 
; and stores it at DataAddr and DataAddr+2. 





MACRO 






ilab 


PopLon 


g 


(DataAddr 


ilab 


PLA 








5TA 




(DataAddr 




PLA 








STA 




(DataAddr+2 




MEND 







-, PopWord DataAddr 

•, This macro pops a word off the stack 
; and stores it at DataAddr. 
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MACRO 
Alab PopWord iDataAddr 
ilab PLA 

STA iDataAddr 

MEND 



STR 'a at i 



Stores the specified character string in memory 
preceded by a length byte. 

MACRQ 
4LAB STR SStrjng 
4LAB DC 11 'LiiString' 

DC C'UString' 1 

MEND 
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CHAPTER 3 



Using the gs 
Tools 



Over the past several years, Apple has spent considerable lime and energy devel- 
oping and promoting what it considers to be the ideal method of communication 
between a computer user and a computer program. The chosen method, culled a 
user interface, was first popularized on the Lisa (later renamed the Macintosh XL) 
and the Macintosh, It is based on a desktop metaphor which goes something like 
this: 

• The sereen is tht- desktop 

■ Pictorial icons on the screen represent objects on the desktop (such as file 

folders and clocks 1 

• Rectangular, overlappable windows represent papers on the desktop 

• Pull-down menus at the top ol the screen represent drawers in the desk 

Such an interface requires a "hand" For quickly selecting papers and other objects 
on the desktop and for moving them around; the computers hand is the mouse. To 
Select an object with the mouse, move tin 1 mouse pointer over the object's icon and 
click (press and release i the mouse button. To drag an object to another part of the 
sereen, move the mouse pointer over the object, press the mouse button, move the 
mouse while holding the button down, and then i liutton when the object 

is where you want it to be 

A complete description of the desktop environment can be found in Apple 
Computer, Ine.'s Hitman Interface Guidelines. (See appendix 8.) Be sure to read 
this book before attempting to develop professional -quaUty software for the gs. 

To promote the use of the desktop environment on the gs. Apple provides an 
extensive set of software tools that programmers can use to manage all aspects oJ 
the interface. Some of these tools are built into the Gs ROM; others are loaded into 
RAM from disk when an application begins to run. The availability of these tools 
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means most CS-specific programs will use them. As a result, users can concentrate 
on mastering the unique portions of a new program instead ofits user interface 

As will be discussed below, there are also tools that perform standard operations 
more directly related to the operating system than to the desktop interlace: math- 
ematical calculations, interactions with I/O devices, memory management, and so 
on. 

The GS tools are simply a series of 65816 subroutines called functions: For 
convenience, the functions are divided into several logical groups called tool sets' 
tin- functions in a particular tool set perform the same general type of operation: 
memory management, window handling, menu handling, and other tasks. 

This chapter describes the tool sets that are available on the r;s and shows you 
how to access them from within programs. The process of writing new too! sets from 
scratch and making them available to your applications is also covered. 

TOOL SET SUMMARY 

Table 3-1 shows what tool sets are available for the CS and gives the names of the 
corresponding APW macro definition files, it also indicates whether the tool sets 
are located in ROM or whether they must be loaded into RAM from disk by the 
application. (RAM -based tool sets must be stored in the SYSTEM/TOOLS/ subdi- 
rectory of the boot disk. See chapter 10.) Keep in mind that as bugs are eradicated, 
Apple will begin to move more of the RAM-based tools to ROM in order to free up 
disk space and improve program performance. 

Later chapters will examine most of the common GS tool sets by describing their 
Functions and showing how to use them in programs. This chapter merely summa- 
rizes the main features of each of the standard tool sets, 

Tool Locator 

The Tool Locator is responsible for the smooth, concurrent operation of all the CS 
tool sets Most applications use it explicitly for only two reasons: to load RAM-based 
tool sets from disk and to install custom tool sets. Many tool sets use the Tool 
Locator implicitly, primarily to save a pointer to a general-purpose workspace in a 
Work Area Pointer Table (WAFT) maintained by the Tool Locator. 

Memory Manager 

An application uses the Memory Manager to allocate blocks of memory that have 
not previously been reserved by the operating system or another application. This 
means programmers no longer have to worry about memory conflicts. The other 
major function of the Memory Manager is to free up previously allocated blocks. 
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Table 3-1: 


The Standard Apple lies Tool Sets 




Tool Set 








Number 


Tool Set Name 




APW Macro File 


I 


♦Tool Locator 




M 16 LOCATOR 


2 


*Meimory Manager 




M16. MEMORY 


3 


* Miscellaneous Tool Set 




M16.MISCTOOL 


1 


♦QuickDraw II 




M 16. QUICKDRAW 


5 


♦Desk Manager 




M16.DESK 


6 


♦Event Manager 




M 16. EVENT 


7 


* Scheduler 




M16 SCHEDULER 


8 


* Sound Manager 




M16. SOUND 


9 


♦DeskTop Bus Tool Set 




M16.ADB 


10 


♦Floating-Point Numerics 


(SANE) 


M 16. SANE 


il 


♦Integer Math Tool Set 




M16.INTMATH 


!2 


♦Text Tool Set 




M16.TEXTTOOL 


13 


♦RAM Disk Tool Set 




[internal use] 


U 


Window Manager 




M 16 WINDOW 


15 


Menu Manager 




M 16. MENU 


L6 


Control Manager 




M16.CONTROL 


17 


System Loader 




M 16. LOADER 


18 


QuickDraw Auxiliary Too] Set 


M16.QDAUX 


19 


Print Manager 




M 16. PRINT 


20 


LmeEdit 




M16.LINEEDIT 


21 


Dialog Manager 




M 16. DIALOG 


22 


Scrap Manager 




M 16. SCRAP 


2:i 


Standard File Operations 


Tool Set 


M16.STDFILE 


;>4 


Disk Utilities 




[none] 


2a 


Note Synthesizer 




M16.NOTESYN 
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Table 3-1: Continued 



Toot Set 






\ umber 


Tool Set Name 


AFW Macro File 


26 


Note Sequ< 


[none] 


27 


Font Manager 


M16 FONT 


28 


List Manager 


MIS LIST 



VOTE; Tool sets marked by an asterisk (*) are in ROM. 



Miscellaneous Tool Set 



Applications do not often use the Miscellaneous Tool Set because it performs low- 
level tasks that are usually handled by the operating system, such as assigning ID 
tags to memory blocks, setting the date and time, and enabling interrupts, 

QuickDraw II 

QuickDraw II is the largest and most complex of the GS tool sets. Its main duties 
are to perform all drawing operations on the super high-resolution screen; activities 
such as plotting points, drawing lines, filling shapes, and displaying characters. In 
addition, it controls pen positioning, defines coordinate systems, and changes draw- 
ing parameters (such as color, pen size, and other characteristics). 

Desk Manager 

The Desk Manager allows you to install Classic Desk Accessories (CDAs) and New- 
Desk Accessories (NDAs) in the system. A CDA is an accessory, such as the Control 
Panel, that you can call up by pressing Control-OpenApple-Ese from the keyboard. 
An NDA is an accessory that you can call up in a desktop environment by selecting 
its name from a pull-down menu. 



Event Manager 

Generally speaking, an event is the occurrence of a condition caused by an I/O 
device like the keyboard or the mouse. The most common events are the pressing 
of a key or the mouse button and the release of the mouse button. Two types of 
events are not lied to I/O devices at all — update events and activate events; these 
events occur when the appearance of a window needs to be changed. The Event 
Manager is responsible for keeping track of events and reporting them to the 
application when requested to do so. 
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Scheduler 

The Scheduler provides a mechanism Fur ensuring that a Imsv, non-reentrant pro- 
gram module, such as ProDOS 16, will not be called by a program that gets control 
during a system interrupt until tl it* module is no longer busy. Hie main use ol tins 
tool set is in scheduling the Controt-OpenApple-Esc Classic Desk Accessory inter- 
rupt. As chapter 10 will discuss, you will also use it when installing certain types of 
interrupt-handling subroutines into ProDOS L6, 

Sound Manager 

The Sound Manager lets you control the behavior ol the c;s's Ensoniq DOC sound 
synthesizer. It also includes functions for accessing the 64K RAM area dedicated to 
the DOC. 

DeskTop Bus Tool Set 

The DeskTop Bus Tool Set lets you communicate with input devices connected to 
the Apple DeskTop Bus, 

Floating-Point Numerics (SANE) 

Flu floating-point Numerics tool set implements the Standard Apple Nuiimiu 
Environment. It is made up of a group of functions that applications can use to 
perform floating-point mathematical operations. 

Integer Math Tool Set 

The Integer Math Tool Set contains functions that permit the mathematical manip- 
ulation of integer numbers. This tool sit also contains nine convenient number 
conversion utilities, which are described in appendix 4. 

Text Tool Set 

The Text Tool Set is important to programs that wish to use the text screen, rather 
than the super high-resolution graphics screen, for output, With this tool set, a 
program can print characters to the screen, much as traditional lie software does. 
You can also use this tool set to redirect character output to a printer. The Text Tool 
Set is actually quite general: you can use it to send characters to any port or slot or 
to get input from any port or slot (or directly from the keyboard), 

RAM Disk Tool Set 

This tool set is for use by the operating system only; applications must not use it. 
it is called to control all operations related to the RAM Disk device you can create 
with the Control Panel. 
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Window Manager 

The Window Manager is responsible for all activities related to windows: creating 
them, destroying them., dragging them around the screen, re-sizing them, and so 
on. 



Menu Manager 

The Menu Manager contains the functions an application needs to create and manage 
pull-down menus in the desktop environment. 

Control Manager 

A control is an object that can be selected to cause an immediate action or to set a 
parameter that will affect a future action. With the Control Manager you can 
associate various types of controls with a window. The main standard controls are 
push buttons, checkboxes, radio buttons, editable text, and scroll bars. The control 
manager also lets you define your own controls. 

System Loader 

The main function of the System Loader is to load a ProDOS 16 application (filetype 
S16) or any other type of ProDOS 16 load file from disk into memory so that it can 
be executed, [t also takes care of two major preliminary steps: determining the size 
of the application and reserving (with the Memory Manager) a block of memory at 
which it can be loaded, (Some applications may require more than one block.) The 
System Loader is loaded into memory when you boot a ProDOS 16 disk. 

QuickDraw Auxiliary Tool Set 

The Quickdraw Auxiliary Tool Set contains additional functions for the QuickDraw 
11 tool set. 



Print Manager 

The Print Manager is a set of functions that lets you send text and graphics to a 
printer instead of to the scr 



LineEdit 

The Line Edit tool set lets you edit lines of text in a manner consistent with Apple's 
user-interface guidelines. It supports standard cut. copy, past* J> I, h mid range- 
selection operations. 
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Dialog Manager 

The Dialog Manager controls the use of dialog and alert boxes. Programs use these 
boxes when they have important messages to display or when they want the user 
to enter information, 

Scrap Manager 

The Scrap Manager contains functions for transferring data to and from a data storage 
area called the clipboard. Using a clipboard makes it possible to easily transfer from 
one program to another, or even between different modules of the same program. 

Standard File Operations Tool Set 

The Standard File Operations Tool Set provides standard dialog boxes to be used 
when the applications need to know the name of a file to be opened or saved. 

Note Synthesizer 

The Note Synthesizer lets you program the Fnsoniq DOC sound synthesizer to play 
musical notes with user-defined instruments. 

Note Sequencer 

The Note Sequencer has functions that let you play back a user-definable sequence 
of notes. The frequency and duration of the notes can be set by the applicalk 



tion. 



Font Manager 

The Font Manager functions let you manage character fouls stored in the SYSTEM/ 
FONTS/ directory on disk. With this tool set, an application can easily load and 
select fonts and choose font attributes. 

List Manager 

The List Manager lets you simplify the handling of lists of items. The items could 
represent filenames, strings, fonts, color patterns, or any other group of data ele- 
ments that have the same row height on the graphics screen. The items in a list can 
be displayed in such a way that the user can move through the list using a vertical 
scroll bar, 

USING THE TOOLS 

Apple has developed a standard technique for calling any function of any tool set. 
To use this technique, the 65816 must be in full native mode with 16-bit X, Y, and 
A registers. If it is not. an error occurs. 
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Here is the procedure lu follow: 

1. Reserve a space on the stack for the results returned by the function (if any). 
You can do this with any instruction that pushes data on the stack, although 
PHA is just as convenient as any other. 

2. Push on the stack all input parameters required by the function (if any). 
These parameters can be numeric constants (words or long words), pointers, 
or handles, 

3. Load the X register with the ID number for the Function; 

256 * (function number) + tool set number 

That is, put the tool set number in the low-order part of X and the function 
number in the high-order part, 

4. Make a long subroutine call (with JSL) to the system tool dispatcher at 
$E 10000. If calling a function for a user defined tool set {see below), call the 
user tool dispatcher at SE 10008 instead. 

On return, any results are on the top of the stack and must he removed with one 
or more pull operations (PLA, PLX, or PLY). 

If an error occurs, the tool dispatcher sets the carry flag and returns with an error 
code in the accumulator 

A specific example will make it easier to understand what is involved in calling 
a function. Suppose you want to use the TaskMaster function in the Window 
Manager tool set. This function has two input parameters and returns a word as a 
result. Here is how to call it: 

PHA ;Create stack space for result (word) 

PEA tFFFF ;Puah first input parameter (word) 

PEA TaskRec|-l6 ;Push second parameter (high) 

PEA TaskRec ; ,.. and (low). 

LDX #*1D0E {Function (high) and looI set (low) 

JSL $ E 1 {Call the system tool dispatcher 

PLA - r Pop the result into the 

STA TheResult ; two bytes beginning at TheResult 

It is important to understand precisely what is happening in this sequence of code. 
Because the function returns a two-byte result, the first step is to push space for it 
on the stack with a PHA instruction (in full native mode, this decrements the stack 
pointer by two bytes; if the function had returned a four-byte result, two PHA 
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instructions would have been used to reserve space}. Next, each input parameter is 
pushed on the stack in the order dictated by the function definition. In the example, 
the first parameter is a word-sized constant and is pushed with a PEA instruction, 
The second parameter is a lung address, so it is pushed (high-order word first) with 
two successive PEA instructions. 

The LDX instruction loads the X register with the tool set ($0E) and function 
($1 D) numbers so that the tool dispatcher, called with the JSL $ El 0000 instruction, 
knows the function to which you want to pass control. 

Finally, the result is pulled from the stack with a PLA instruction. If the result 
was a two-word quantity, you would pull twice and the low-order word would come 
off the stack first 

Remember that when you use a function which returns a result, you must push 
space for tin* result on the stack before calling it, and you must remove the result 
when the function ends. Failure to follow these two rules will put the stack out of 
kilter and could eventually cause your program to crash. 



Data Types Used by Functions 

The input or output parameters of a function can be one of three sizes: byte, word 
(two bytes), or long word (four bytes). If a parameter represents a numeric quantity 
(as opposed to an address; its data type is said to be integer for a word-sized number. 
Boolean for a true 'false word-sized number, and long integer for a long- word-sized 
number. A Boolean parameter is one that is true (non-zero) or false (zero). 

Note that addresses passed to functions are always four bytes long even though 
the 65816 uses only three bytes 24 bits) to form a long address. The extra byte 
(always $00] makes sure that there is always an integral number of parametei words 
on the stack, which makes them easier to access with word-sized (16-bit) operations. 

The data type of an address is either pointer or handle. By convention, symbolic 
names lor such data types end in "Ptr or "Hindi. " A pointer is simply the address 
of a data structure somewhere in memory. A handle is the address, not ol a data 
structure itself, but of a location that contains a pointer to the data structure. Pointers 
and handles arc described in greater detail in the next chapter. 



Tool Set Macros 

Table 3-1 (see above) contains the names of the APVV macro definition files for each 
<;s tool set. Von can extract the macro definitions your program needs with the 
MACGEN command prior to assembling the program. As explained in chapter 2, 
the purpose ol the tool set macro files is to assign a standard symbolic name to the 
LDX/JSL calling sequence for each tool set function. By convention, all function 
ii. uties begin with an underscore character, The name JTask Master, for example, 
refers to function $1D in tool set SOD (the Window Manager). 
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APW also comes with a set of general-purpose macros in the M 16. UTILITY file. 
Three of these macros (PushVVord, Push Long, and PushFtr) are particularly useful 
for pushing parameters on the stack prior to making a tool set function call and are 
similar to the macros listed at the end of chapter 2. 

To push a parameter, use PushVVord (for words), PushLong (for long words), or 
PushPtr (for address pointers). PushVVord and PushLong are able to push numbers 
stored at an address or immediate numbers: 

PushWord MyParm ;Push the word at MyParm 

PushWord #10 ;Push a 10 {immediate) 

PushLong MySize ;Puah the long word at MySize 

PushLong #I7FFFFF ;Puah a I7FFFFF (immediate) 

PushPtr MyDataArea ;Push the address of MyDataSize 

Notice that the arguments for the two macros involving immediate numbers are 
preceded by a "#" sign. 

At assembly time, these macros are expanded into the Following code sequences: 

LDA MyParm 

PHA ;Pu5hWord MyParm 

PEA 10 ;PushWord #10 

LDA MySize-2 

PHA 

LDA MySize 

PHA ^PushLong MySize 

PEA I7FFFFF-16 

PEA S7FFFFF jPushLong #$7FFFFF 

PEA MyDataArea|-16 

PEA MyData ;PushPtr MyDataArea 

Notice that the immediate forms of PushWord and PushLong push the constants on 
the stack with PEA instructions. This conveniently avoids destroying the contents 
of the A register :<>r any other register). 

The PushPtr macro pushes the address specified in its argument onto the stack 
in the same way that the immediate form of PushLong pushes its numeric argument. 
In fact, the only difference between PushPtr and PushLong is thai PushPtr* S argu- 
ment does not require a leading number sign. 

The two macros listed in chapter 2 lor removing results from the stack were 
PopWord (for words) and PopLong (Tor long words). The argument for each is the 
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addrt-ss at which the result is to be stored. For example, "Pop Word The Result" is 
equivalent to the following code sequence- 

PLA 

STA Thefcesult ;PopUJord 

and Pop Long MyAddress is equivalent to: 

PLA 

STA MyAddreas 

PLA 

STA MyAddresa + 2 -.PopLong 

By using these five simple pull and pop macros and the tool set function macros, 
you can make your source code more understandable and easier to maintain. In 
addition, the chances of committing errors, such as pushing or pulling two-word 
quantities in the wrong order, are minimized. 

THE TOOL LOCATOR 

The first tool set you should know about is the Tool Locator because it manages all 
the other tool sets. The main Functions in the Tool Locator are summarized in table 
R3-I at the end of the chapter, and will be examined in more detail later in this 
chapter. 

Only a few Tm»l Locator functions will ever be needed by most applications, The 
first. TLStartup. prepares the Tool Locator for operation and must be called before 
using the functions it supports or functions of any other tool set. TLShutDown 
"turns off" the Tool Locator and should be called just before your application ends, 
after the program calls the Shut Down functions of any other tools that have been 
started up. .Neither TLStartup nor TLShutDown requires any input parameters, 
and neither return a result. 

The LoadTools function loads RAM-based tool sets from disk into memory so that 
their functions can be called by an application. Its only parameter is a pointer to a 
tool set load table containing a list of the ID numbers and version numbers of the 
tool sets to be loaded. For this loading scheme to work properly, the tool sets must 
be stored in disk files having names of the form TOOLxxx, where xxx is the three- 
digit decimal number of the tool set, In addition, these files must be located in the 
SYSTEMATOOLS/ subdirectory of the start-up disk. 

Here is an example of How to use LoadTools to load twelve standard tool sets 
from disk. 

PushPtr LoadTable 
_LoadTool a 
RTS 
LoadTable DC I2M2' ^Number of tool sets 

DC 1 2 • 1 4 » ' ;Window Manager 
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DC 


I2M5.0' 


DC 


I 2 ' T 6 , Q ' 


DC 


i2M8,0' 


DC 


12 ' 1 9 , ' 


LC 


I2'20,0' 


DC 


12*21 ,0' 


DC 


12-22,0' 


DC 


12 '23, ' 


DC 


32'25,0' 


DC 


I2'27,Q' 


^C 


I2'2B T 0' 



;Menu Manager 

;Control Manager 

;QuickDraw Auxiliary Tool Set 

;Prmt Manager 

;Line Edit 

; Di a 1 og Manage r 

;Scrap Manager 

;Standard File Operations 

{Note Synthesizer 

; Font Manager 

;List Manager 

Notice how the tool set load table is constructed. The first entry is the number of 
tool set entries stored in the table. Following it are two words for each tool set 
The first is the tool set number; the second is the minimum version number expected 
(a value of means any version will do), LoadTools returns an error if it cannot 
- the proper versions of all the tools listed. (As explained below, errors are 
recorded by setting the carry flag and putting an error code in the accumulator.) 
ii only one tool set has to be loaded, use Load One I 

PushWord TSNum ;tool set number 

PushWord Version [version number 

_LDadOneToQ 1 

You may want to use LoadOneTool in situations where the application can function 
even if the specified tool set is not present. For example, you could use it to try to 
load the Print Manager; if the load fails (the cam- flag is set), the application can 
disable all printing-related commands. If you load a large group of tool sets with 
LoadTools and get an error, you cannot tell which tool set is missing. 

RAM-based tool sets loaded into memory with LoadTools or LoadOneTool remain 
active until you call TLShutDown at the end of the program or until you call 
UnloadOncToul. Whereas TLShutDown removes all RAM-based tools, Unload- 
OneTool removes only one: 

PushWord TSNum ;tool set number 

_UnloadOneTool 

L'se I nloadOneTooI when you are through using a given tool so that the memory 
it occupies will be freed up. 

Von cannot load RAM-based tools if the boot disk is not in a drive. If you try, 
you will get ProDOS error $45 (volume not found). To recover from this, you should 
use TLMountVoluiiie to display a dialog box asking (he user to insert the boot disk. 
The application can try again when the user clicks the Ok button, or it can abort if 
the Cancel button is clicked. 
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An example of how to use TLMountVolume is given in the STANDARD. ASM 
program in listing 3—1. Because TLMountVolume requires QuickDraw and the 
Event Manager to ho active, do not try to load tools until after you have started up 
QuickDraw and the Event Manager. 



THE STRUCTURE OF A TOOL SET 

Each GS tool set may contain up to 255 Functions, numbered irom 1 to 255. A 
function number of is not allowed. By convention, the first eight functions must 
perform certain specific actions dictated by the operating system — other functions 
can do anything the designer of the tool set wants them to do. 

Of the first eight functions, two arc reserved for future expansion (#7 and #8). 
Here is what the other six standard functions do: 

Bootlnil (#1). This Function performs any preliminary initialization of the tool 
set which might he necessary. The system monitor firmware calls it when the 
system starts up or, if the tool is RAM-based, when the tool is first loaded from 
disk. Applications must not call this function. 

Startup (#2). This function prepares the tool set For action. An application must 
call it before using any other function in the tool set. Many tool sets require 
input parameters for their Startup functions; a common parameter is a bank $00 
address used by the tool set as the base of a private direct page. 

ShutDown (#3). This function releases any memory space allocated by the tool 
set since start-up, including memory pointed to by the work area pointer table 
(the WAFT is described below). An application should call this function just 
before it ends. 

Version (#4). This function returns the version number of the tool set (a word). 
It requires no input parameters, so the calling sequence is: 

PHA ;apace for result 

-xxxVersion 

PLA *,pop the version number result 

The major version number is in the high byte and the minor version number 
is in the low byte of the result. If the tool set is in the prototype stage, the 
high-order bit of the high-order byte is set to 1. 

Reset (#5,). This function returns the tool set to a known, default state. It is 
called when a system reset occurs 

Status i#6). This function returns true (non-zero) if the tool set is active and 
false (zero) if it is not. 
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Of these six standard functions, only two of them. Startup and Shut Down, are really 
needed by most applications. In later chapters, when specific tool sets are discussed, 
these will be the only reserved functions mentioned. Keep in mind, however, that 
the Bootlnit, Version, Reset, and Status functions are always present — they just are 
not used often. 

Almost every program you write for the cs will begin by loading RAM-based tool 
sets from disk and calling the Startup function fur each tool set the program uses. 
When a program ends, it will call the ShutDown function for each tool set. To 
simplify these operations, you should develop a standard program subroutine like 
the one in the STANDARD. ASM program in listing 3-1 and include it in your 
program source file with the COPY directive. 

STANDARD.ASM has two entry points, DoStarlup and DoShutDown. Call 
DoStartup at the beginning of a program to load all tools and to start up tool sets 
in the proper order. (The order is important because some tool sets rely on the 
presence of others before they will work,) Call DoShutDown to shut down all the 
tool sets and exit the program. Depending on the program you are developing, you 
may want to modify STANDARD.ASM to add or eliminate the group of tool sets it 
uses, If you change the LoadTools tool table, be sure to set the leading count word 
("11" in the example) to the proper value You will also have to modify the tool set 
start-up and shut-down sequences. 

As listed, STANDARD.ASM starts the application up in the 64G-by-200 graphics 
display mode. To set up 320-by-200 graphics instead, change VidModc and 
XMaxClamp to S00 and 320, respectively. 

Notice that STANDARD.ASM also assigns several global symbolic labels to nu- 
meric constants. This is convenient, because it forces you to use the same labels in 
all your programs, thus making them easier to read. 

DEVELOPING YOUR OWN TOOL SET 

Associated with each tool set is a table of pointers to each of its junction handlers, 
in function number order l 

Number of functions plus 1 (4 bytes) 
Address of Bootlnit function minus 1 (4 bytes) 
Address of Startup function minus 1 (4 bytes) 
Address of ShutDown function minus 1 (4 bytes) 
Address of Version function minus 1 (4 bytes) 
Address of Reset function minus 1 (4 bytes) 
Address of Status function minus 1 (4 bytes) 
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Address of Reserved function minus 1 (4 bytes) 
Address of Reserved function minus 1 (4 bytes) 
Address of Function #9 minus 1 (4 bytes) 



Address of Function #n minus I (4 bytes) 



This is called a function pointer table (FPT). 

To install a new tool set, you must insert a pointer to its FPT in one of the tool 
pointer tables (TPT) maintained by the Tool Locator (there is a system TPT for 
standard system tools and a user TPT for user-defined tools). Do this with the Tool 
Locator's SetTSPtr function: 

PushWord #18000 -,800Q = u3er, Q^aystem TPT 

PushUlprd #243 ;This ib the tool set number 

PushPtr tfyFPT ;Pointer to new FPT 

_SetTSPtr ; Install pointer in TPT 

The tool set number can be auy number from 1 to 255 that is not already in use by 
another active tool set. 

The first word pushed on the stack is the SystemOrUser word' It indicates 
whether you are dealing with system tool sets ($0000) or user-defined tool sets 
($8000). Tool sets that are not just replacements for existing system tool sets should 
be added to the user TPT. 

The Function handlers pointed to by the FPT can be located anywhere in memory, 
but they cannot be allowed to move because the pointers to them would become 
invalid. The code for a function should be re-entrant, if possible; that is, the function 
should work even if it is interrupted and called by an interrupt handler or a Classic- 
Desk Accessory, If it is not, the function must increment the Scheduler's busy flag 
when it gets control by performing a JSL SE 10064 instruction in hill native mode. 
If it does this, it must decrement the busy flag on exit with a JSL SE10068 instruc- 
tion. Properly-designed interrupt handlers will not make tool set calls when the 
busy flag is n on -zero. 

When a function handler gets control, the 65816 is in full native mode, and the 
stack is configured as fnlkms; 
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1 .,,_ 




parameters 


JSL Return Address 






JSL Return Address 







SP+7 



< stack pointer 



The last of the two 3-byte return addresses is caused by a JSL from the tool 
dispatcher to the function handler. The first is caused by the JSL to the tool 
dispatcher (at $E 10000 or |£ 10006) itself. 

This means that the parameters pushed on the stack by the application before it 
calls the tool dispatcher begin at SP + 7 (7 bytes past the current stack pointer value). 
Note that the offset is 7, not 6, because SP points to the first byte past the last 
return address, not to the return address itself. 

• Warning! These offsets remain valid only if the function handler does not push 
anything on the stack after gaining control. If it does, use- offsets that take this 
into account. 

To access parameters passed on the stack in this way, use the stack relative address- 
ing mode, "sr,S". Suppose, for example, that the function has two input parameters, 
the first being a word and the second a long word, and the function returns a word 
result. To read the first parameter, use the instruction; 



LDA 1 1 ,S 



;Gel 1st parameter 



The offset of 1 1 is the sum of the basic offset, 7, and the space occupied by all 
parameters pushed after the first parameter (1 bytes for the single long word 
parameter in this example). The operands for accessing the second parameter would 
be 7.S (low-order word) and 9.S (high-order word). 

The function handler returns a result by storing it directly into the space for the 
result on the stack. In this example, this space is at a location given by SIM 13 the 
address of the first parameter pushed plus the size of the first parameter). 

Before it finishes, a function must remove all input parameters (but not the result) 
from the stack. It can do this by moving the two return addresses to positions x 
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LDA 


5,5 


STA 


15,5 


LDA 


3,5 


STA 


13,5 


LDA 


1,3 


STA 


11 ,S 


TSC 




CLC 




ADC 


#10 


TCS 





bytes higher in memory, where x is the total size of all the input parameters. The 
stack pointer must then he incremented by X bytes before the function ends. For 
instance; if there are 10 bytes of parameters, you would use the following code 
segment: 

Move SP+1 through SP+6 
(the two return addresses) 
up 10 bytes to 5P+15 



j Put SP in A register 

-, . . . add 10 to SP 
; 5ave new SP 



A function reports errors by setting the carry flag and storing an error code in the 
A register before ending with an RTL instruction, The error code actually occupies 
the lower 8 bits of the A register; the upper 8 bits hold the tool set number. The 
assignment of error conditions to error codes is up to the designer ol the function. 

If no error occurs, a function returns with the A register zeroed and the carry 
flag clear. A neat way of setting the carry flag properly, error or no error, is to exit 
with a CMP #1, RTL instruction sequence. 

Note that a function need not preserve the contents of the X and Y registers. 
The direct page and data bank (and code bank) registers cannot change, however; 
they must be the same on exit as on entry. Of the status register bits, m, i\ e, and 
/ must be unchanged and the decimal mode flag must be zero. 

Error Codes 

Error codes from $000] to S0O0F are reserved for use by the function dispatcher. 



Of these, only two are currently used: 

$ 1 The tool set does not exist 

$ 2 The tool set function does not exist 

The function dispatcher may also return a $FFFF code; this means that the call to 
the dispatcher was not made in full native mode, 

Error codes returned by functions themselves range from $xx0l to $xxFF, where 
xx represents the too! set number. One of these, SxxFF, has a special meaning, 
namely, "the function is not implemented." 
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Work Areas 

A tool set may require a private work area in which its functions can store config- 
uration information and other data which must be saved between function calls. If 
the work area is not located in bank $00, function #1 of the tool set (Bootlnit) should 
reserve the space for it with the Memory Manager (see chapter 4). 

Bank $00 areas are dealt with differently because they are prime real estate. Bank 
$00 is the only bank in which a direct page can be set up. By convention, if a tool 
set needs direct page space for a work area, the application must allocate it and puss 
its address to function #2 (Startup), 

The tool set must place a pointer to its work area in a table called the Work Area 
Pointer Table (WAPT). (The pointer is zero if the tool set does not use the WAFT.) 
Jt can do this with the Tool Locator's SetWAP function. When a function handler 
takes control the entry in the WAPT is always in the A (low-order word) and Y 
(high-order word) registers. 

If the work area is in bank $00, the first thing the function handler should do is 
save the current contents of the direct page register on the stack and set the new 
direct page to the work area: 

PHD ; Save direct page register 

TCD ;"C» (16-bit A register) holds d.p. 

Because this pushes an extra word on the stack, the address of the last parameter 
passed to the function is SP + 9 and not SF + 7. 

Before returning to the tool dispatcher with an RTL, restore the previous direct 
page with a PLD instruction. 

A USER -DEFINED TOOL SET 

The program in listing 3-2 shows how to install a user-defined tool set called 
TimeTools. The program does this by passing a pointer to the tool set function 
pointer table to the SetTSPtr function. This table holds pointers to the eight standard 
functions every tool set must support and to one special function called DayOfWeek. 
You can use the DayOfWeek function to return a character string containing the 
name of the current day of the week. 

The start-up function for the new tool set, TTStartup, expects a direct page 
'ress (a word] to be on the stack when it is called. It places this address in the 
WAPT using the SetWAP function. None of the TimeTools actually use this direct 
page area; the purpose of requiring it is simply to illustrate how to deal with work 
area pointers. The TTShutDown function clears the WAPT entrv for the tool set 
toO. 

The TTStatus function returns a Boolean (word) result indicating whether the 
TimeTools are active. It returns true if the WAPT entry is non-zero (which means 
that TTStartup has been called). 
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The TimeToois tool set has one non-required function, DayOfWeek, which is 
assigned to function #9. It expects one input parameter: a pointer to a 10-bytc 
burler allocated by the application calling the function, DayOfWeek returns a char- 
acter string in this buffer describing the day of the week. 

DayOfWeek determines the day ol the week by calling ReadTimeHex, a function 
in the Miscellaneous tool set that returns all time and date parameters in binary 
form (see chapter 5). It then takes the code for day of week (I = Sunday, 2 = 
Monday, and so on), converts it to an ASCII-encoded string, and places it in the 
buffer, preceded b> a length byte. It then removes the input parameter from the 
stack and returns. 

Notice that GetDayOfWeek returns an error code of 1 if it receives a day of week 
code which is or above 7. It dues this by putting the error code in the accumulator 
and setting the cany flag by comparing the accumulator with I. 

Once the TimeToois tool set is installed, you can call its functions from anywhere 
inside the installation program. To call the DayOfWeek function, for example, use 
the following calling sequence: 

PushPtr DOW.Buffer {Pointer to buffer 

LDX #10901 ; Function 9 / tool set 1 

JSL IE10008 ; (not £100001 ) 

RTS 

DOU_Buffer DS 10 ;Space for length + name 

The program in listing 3—2 calls DayOfWeek in this way before displaying the day 
of the week on the 80-coIuinu text screen. 

Notice that the JSL in this example is to location SE100Q8 r the entry point to 
the user function dispatcher, not to location $E 10000. 

It is important to realize that you cannot use the TimeToois tool set from another 
application, because the memory il occupies is purged when the installation program 
m listing 3-2 ends. In any event, the user tool pointer table is cleared when the 
TLStartup or TLShutDuwn functions are called. 

To allow a custom tool set to be used by an) application, you must install it in 
the system tool pointer table. To do this, first choose a tool set number that is not 
already used by any other HAM- or ROM -based loo] set. Then prepare a source File 
containing just the code defining the tool set. For the tool set in listing 3-2, for 
example, retain the ToolSct code segment only, change TS_NUM to the selected 
tool set number and change UserOrSys to $(MMM) to mark this as a system tool set. 

Next, assemble and link the source file and then change the file type rode ol the 
EXE lite created to &BA using the APU FILETYPE command. (ProDOS 16 rec- 
ognizes only SUA liles as system tool sets.) Finally, transfer the $BA file to the 
SYSTEM/TOOLS; directory On the boot disk. After loading the tool set with 
LoadTools or EoadOneTool. applications can use it. 
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REFERENCE SECTION 

Table R3-1: The Major Functions of the Tool Locator Tool Set (SOD 





Fu notion 


Stack 


Description of 


Function Name 


Number 


Parameters 


Parameter 


GetFuncPtr 


$0B 


result (L) 


ptr to Function handler 






SystemOrUser (W) 


= sy stem/$8000 = user 






FuneTSNum (W) 


function <high)/tool set (low) 


GetTSFtr 


.$09 


result (L) 


ptr to function pointer table 






SystemOrUser (W) 


» system/98000 = user 






TSN umber (W) 


tool set number 


Gel WAP 


SOC 


result (L) 


ptr to tool set work area 






SystemOrUser (W) 


- S ystern/$80O0 = user 






TSN umber (W) 


tool set number 


LoanOneTool 


$0F 


TSNumber (W) 


tool set number to load 






Min Version (W) 


minimum version required 


LoadTools 


$0E 


ToolTable (L) 


ptr to tool set load table 


SetTSPtr 


$0A 


SystemOrUser 


= system/$8000 = user 






TSNumber \\ 


tool set number 






FPTptr (L) 


ptr to function pointer table 


SetWAP 


$0D 


SystemOrUser (W) 


- system/$8000 = user 






TSNumber (W) 


tool set number 






WAPptr (L) 


ptr to work area 


TL Mount Volume 


$11 


result (W) 


1 = OK, 2 = Cancel 

selected 






VVhrreX (W) 


upper left-hand X 
coordinate 






WhereY(W) 


upper left-hand Y 
coordinate 






LinelFtr [L 


ptr to string at top of box 






Linc2Ptr (L) 


ptr to string below line 2 
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Function \ame 


Function 
Number 


Stack 
Parameters 


Description of 
Parameter 








ButlomlPtr (L) 


ptr to text for OK button 








Butlon2Ptr L' 


ptr to text tor Cancel button 


TLShutDown 


|03 




|iio parameters] 




TLSlartup 


SU2 




[no parameters] 




UnloadOneTool 


S10 




TSNumber (V, 


tool set number to unload 



Table R3— 2: Tool Locator Error Codes 



Error 

Code 


Description of Error Condition 


$0110 


The specified minimum tool set version was not found, 


note. LoadTools 


and LoadOni'Tool can also return Pro DOS error codes 
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Listing 3-1: The STANDARD. ASM Program with Standard Tool Start-up and 
Shut-down Sequences 



DoStartup and DoShutdown are standard opening 
and closing sequences for most programs. 

Set VidMode and XMaxClamp as appropriate fop the 
video mode you're using (320x200 or 6-40x200). 

All the tools referred to in ToolTable must be in 
the SYSTEM/TOOLS./ directory. If you're missing some, 
remove the entry from the table, change the initial 
count byte, and remove the Startup and ShutDown calls. 

DoStartup START 

« Direct page equates 



DeRefLoc GEQU 
DPAddress GEQU 

• General equate 



,0 '.LONG {used for dereferencing handle) 

DeRefl_oc + 4 ; INTEGER (address of direct page) 



False 




GEQU 


soooo 


True 




GEQU 


53000 


VidMode 




GEQU 


58D 


XMaxClamp 


GEQU 


640 



* Point offsets: 



■•-•■ 
h 



GEQU 

GEQU 



• Rectangle offsets: 



top 


GEQU 





left 


GEQU 


2 


bot torn 


GEQU 


< 


right 


GEQU 


6 



;Boolean false 
*, Boolean true 

-, »S0 - 640x200, $00 = 320x200 
;Video width (640 or 320) 



;Vertical position 
;Horizontal position 



* GetNextEvent and TaskMaster result codes: 



btnDownEvt GEQU 1 

IceyDownEvt GEQU 3 

autoKeyEvt GEQU 5 

updateEvt GEQU 6 

activateEvt GEQU 8 

wlntlenuBar GEQU 17 

wlnContent GEQU 19 
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;mouse-down event 

; key down event 

;auto-Jtey event 

;update event 

;act i vale event 

; in menu bar 

;in content region of window 



wlnGoAway GEQU 22 

wlnSpecial GEQU 25 

S Dialog Item Type codes: 

Buttonltem GEQU 10 

Check Item GEQU 11 

Radiol tern GEQU 12 

ScrolJBarltem GEQU 1 3 

UaerCtlltem GEQU 1 4 

StatText GEQU 15 

LongStatText GEQU 16 

EdltLine GEQU 17 

Iconltem GEQU 18 

Picltem GEQU 19 

Userltem GEQU 20 

UsGrCtlItem2 GEQU 21 



jin cl ose box 

;in special menu item 



Using StartData 

PHK 
PLB 

_TLStartup 
_MTStar tup 

PHA 

_MMStar tup 
PopWord Ny ID 



;Data bank = program bank 

-.Tool Locator 
*,Misce 1 laneous Tools 

', space for resul t 
•.Memory Manager 



; Get direct page memory for the tool sets: 



PHA 




PHA 




PushLon 


g *SD00 


PushWor 


d MylD 


PushWor 


d #fCQQS 


PushLon 


9 *0 


_NewHan 


die 


P o p L o n g 


DeRefLoc 


LDA 


[DeRefLoc J 


5TA 


DPAddress 



PushWord DPAddress 
PuahWord #VidMode 
PushWord #160 
PuahWord MylD 
_QDStartup 

_ 1 ni t Cursor 



•.Space for handle 

•.Thirteen pages 

*, 1 D tag to use 

.Locked, fixed, aligned, fixed bank 

-.Bank 100 



^Dereference the handle 

; and save the pointer (low) 

;DP to use (3 pages) 
-.Graphics mode 
-.max width 
*. ID tag to use 

^QuickDraw II 

1 Display arrow cursor 
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LDA DPAddress 

CLC 

ADC #1300 ;one page 

PHA 

PushWord #0 jqueue size (default) 

PushWord #0 ; x min for clamp 

PushWord #XMaxClamp ;x max for clamp 

PushWord #Q i y nriln for clamp 

PushWord #200 ;y max for clamp 

PushWord MylD 5 ID tag to use 

_EM5tartUp ;Event Manager 

• Now load the RAM-baaed tools: 

GetTools PushPtr ToolTable 
_LoadTools 
BCC StartMore 

CMP #$45 (Error was Volume Not Found' 

BNE Abort ;No, so branch 

JSR AskForDisk iAsk for boot volume 

CMP #1 ;OK? 

BEO GetTools ;Ves, so branch 

Abort PLA »( remove return address) 

JMP DoShutT 

;Start up the rest of the tool sets: 
StartMore ANOP 

_QDAuxStartup -.QuickDraw Auxiliary Tools 

PushWord MylD 

LDA DPAddress 

CLC 

ADC *$400 *,one page 

PHA 

_CtlStartup ^Control Manager 

PushWord MylD 

_WindStartup ;Window Manager 

PushLong #0 

_Ref reshDesktop ;Draw the screen 



90 Using the cs Tools 



PushWord My ID 

LDA DPAddress 

CLC 

ADC #$500 ;one page 

PHA 

_Menu5tartup jMenu Manager 



PushWord MylD 
LDA DPAddress 

CLC 

ADC #t600 ;one page 

PHA 

_LEStartup ;LineEdit 



PushWord MylD 

_Dia 1 ogS tar t up ;Dialog Manager 



PushWord MylD 

LDA DPAddress 

CLC 

ADC *$700 lone page 

PHA 

_SF5tartup ^Standard File Operations 



LDA DPAddress 

CLC 

ADC '$800 ;one page 

PHA 

SoundStar tup -Sound Manager 



; Insert this to start up the Print Manager: 



PushWord MylD 

LDA DPAddress 

CLC 

ADC #$900 ;two pages 

PHA 

_PMStartup ^Print Manager 



PushWord MylD 

LDA DPAddress 

CLC 

ADC *$B00 ;one page 

PHA 

_FMStartup ;Font Manager 
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LDA 


DPAddress 


CLC 




ADC 


#*coo 


PHA 




_SANESt 


ar tup 


_ScrapSiar tup 


_IMStar 


tup 


.DeikSti 


ar tup 



RTS 
AskForDlak ANDP 

GET BOOT VOL GBVParms 





PHA 






PushWor 


d #150 




PushWor 


d #50 




PushPtr 


Pr omp t 1 




PushPtr 


VolName 




PushPtr 


0K_Msg 




PushPtr 


Cancel_Msg 




_TLMoun 


t Vo lume 




PLA 






RTS 




GBVParma 


DC 


14'VolName 


Promp 1 1 


STR 


'Insert th 


VolNanie 


DS 


18 



;one page 

; Numerics (SANE) 

; Scrap Manager 
; I nt eger Math 
; D e s k Manager 



;Get name of boot volume 
; space for result 



;Space for volume name 



0K_Msg STR 'OK' 
Cancel_Mag STR 'Abort 



DoShutDown ENTR^ 



_DeskShutDown 

_ J MShutDown 

_ScrapShu tDoum 

_SANEShutDown 

_FM5hutDown 

_PM5hutDown 

_SoundShu tDown 

_SFShutDown 

_DialogShutDown 

_LE5hutDown 

_MenuShu tDown 



; Ca 1 1 this if using Print Manager 
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DoShutl 



_Wi ndShu tDown 
„Ct IShutDown 
_GDAuxShutDown 

ENTRY 



;Enter here if LoadTools fails 



_EMShu tDown 
_QDShutDown 

Pu5hWord MyJD 
_MM5hu tDown 

_MTShutDown 
TLShutDown 



_Ouit QuitParms 
BRK IFQ 

END 



; (Shouldn't get this far] 



StartData DATA 



My ID 



DS 



luUParms DC 

DC 



14 • • 

I2'0' 



;Return to caller 
; N o special flags 



Table of RAM-based tools to load. Only load the tools you 
have in the SYSTEM/TOOLS/ directory. 



Number of tools to load 

Window Manager 

Menu Manager 

Control Manager 

(System Loader always loaded) 

QuickDraw Aux Tools 

Print Manager 

Line Edit 

Dialog Manager 

Scrap Manager 

Standard File Operations 

Disk Utilities 

Note Synthesizer 

Note Sequencer 

Font Manager 

List Manager 



ToolTable 


DC 


I'll' 




DC 


I M4.S000Q' 




DC 


I » 1 S , * 1 ' 




D : 


I «16,*0000' 


» 


DC 


I ' 1 7 T tOOOO ' 




DC 


1 '18,*Q00Q» 


5 


DC 


1 M9,*QQ00' 




Di, 


] '20 ,$0000' 




DC 


1 "21 ,10000' 




DC 


I '22, $0000' 




DC 


I <23,*00Q0' 


i 


DC 


I '24 ,10000' 




DC 


I '25,*0000 1 


i 


DC 


I '2S,*Q000' 




DC 


1 '27,10000' 




DC 


1 '28,10000 ' 



END 
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Listing 3-2: A Uscr-drfincd Tool Set 



* This program shows what a custom tool set • 

* looks like. The first portion installs • 

* the tool set into the user tool set table. • 



KEEP 

MCQPY 

TS_NUM GEQU 
UserDrSys GEQU 

Installer START 



TOOLSET 
TOOLSET. MAC 

• 01 

18000 



;Tool set number 
;S80QQ = user tool set 



.TLStartup 
_TextStartup 

; This code installs the user tool set: 



PushWord #UserQrSys 
PushWord 'TS_NUM 
PushPtr ToolSet 
_SetT5Ptr 



Tool set type 
Tool set number 
Pointer to FPT 
Install the tool set 



; Now let's test the tool set by showing the day of the week: 



PushPtr TheBuffer 
LDX #TS_NUM*9*25B 
JSL 1E10008 

PushPtr TheBuffer 
_Wr l teS t r i ng 

_Text5hu tDown 
_TLShu tDown 



;Call DayOfWeek function 
; »E1 0008 ■ user dispatcher 



^Display on text screen 
;(this removes user tool sets) 



.QUIT 
BRK 



QuitParms DC 
DC 



Qu j tParms 
*FQ 

I2»0" 



TheBuffer DS 10 

END 
* The tool set definition begins here: 



;Day name returned here 



ToolSet 



START 
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* This is the function pointer table. It contains the addresses, 
« minus 1, of each function subroutine. It begins with a long 

* word containing the number of functions, plus 1. 

;Number of functions (+1) 



DC 


14' (TBL_EHD-ToolSet)/4 


DC 


M'TTBootImt-1 ' 


DC 


M'TTStartup-1 ' 


DC 


!4'TTShutDown-1 ' 


DC 


I 4 ■ TTVersion- 1 ' 


DC 


t4'TTReset-1 ' 


DC 


l4'TTStatus-1 ' 


DC 


14 " Reserved-t • 


DC 


I 4 ' Reserved- 1 ' 


DC 


14'DayDfWeek-l ' 



TBL END 



ANDF 



TTBootlnit LDA 
CLC 

RTL 



tt 



;Null error code 
-,No error 



;TTStartup has one input parameter; a word representing a starting 
; address in bank *Q0 of a one-page work area. On entry to TTStartup, 
; this word is buried S07 bytes into the stack, just above the two 
; 3-byte return addresses. Dn exit, this function removes the input 
; parameter from the stack by moving the two return addresses and the 
; slack pointer up by two bytes. 



TTStartup ANOP 

LDA »07,S 

PushWord 'UserDrSy5 
PushWord *TS_NUM 
PushWord *0 
PHA 
Set WAP 



•,Get direct page address 

Tool set type 

Tool set number 

High word of address (zero) 

Low word of address 



Remove the input parameter from the stack: 



LDA 


s,s 


STA 


7,S 


LDA 


3,5 


STA 


S,S 


LDA 


1 .5 


STA 


3,5 


TSC 




CLC 




ADC 


*2 


TCS 





Move the two long JSL 
return address up by 
two bytes 



*, Increment the SP by 

; two bytes. 

• (Could just do PLA instead) 
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LDA #0 '.Exit with no error 

CLC 
RTL 

;To shutdown this tool set, just zero the entry in the 

; work area pointer table. It is up to the application to 

; dispose of the area it points to (using Di sposerlandle ) . 

TTShutDown ANOP 

PushWord *UserDrSys ;Tool set type 

PushWord *TS_NUM ;Tool set number 

PushLong #0 ;Address is zero 
_SetWAP 

LDA #0 

CLC 

RTL 

TTVersion returns a version word in a space on the 
stack allocated by the caller. The high-order byte 
contains the main version number and the low-order 
byte contains the secondary version number. The 
stack result space begins at an offset of *07 from 
SP because there are two 3-byte return address on 
the top of the stack on entry to TTVersion. 



^Version 2.1 

?Put result in stack space 



TTVers ion 


ANOP 






LDA 


#$0201 




STA 


$07,S 




LDA 


#0 




CLC 






RTL 




TTReset 


L L m 
CLC 
RTL 


*0 



TTStatus returns a Boolean (word) in the stack space 

reserved by the caller. The result is true if TTStartup 
has been called; false otherwise. TTStatus knows if it 
has been called because the WAPT entry will be nonzero. 

TTStatus ANQP 

CMP '0 ; Is UAP { low) zero? 

BEQ SelStatua ;Yes, so store false 

LDA 'SFFFF iTrue code 

96 Using the cs Tools 



SetStatus STA *07,S ;Put result in stack space 

LDA *0 

CLC 

RTL 

Reserved LDA #T5_NUW«2SG+$FF jError «FF means "not implemented 
SEC 

RTL 



* The DayDfWeek function expects one parameter on the stack; a 

* pointer to a data area where the function is to return the 

* day-of-week 5tnng. Note that after the initial PHD and 

» aligning the new direct page with the stack, the pointer 
i is at [109] . 
DayDfWeek ANQP 



QldDP 


EQU 


• 01 


RTL1 


EQU 


OldDP+2 


RTL2 


EOU 


RTL1+3 


ThePtr 


EQU 


RTL2+3 



PHD ;Save current direct page 

;A1 ign d.p. with stack 

j Space for 8 bytes of result 



;Pop minute/second 

;Pop year/hour 

;Pop month /day 

;Pop day of week (high byte) 

;Put day of week in low byte 

; S t r i p unused bits 

^Convert 1..7 to 0..6 (1 -Sunday) 

-.Number in range (0..6)' 
;No, so branch 

; Look for the Nth entry in the table: 

TAY 

LDX #0 

FindEntry CPV *0 '.At correct name? 

BEQ SaveResult ; Yes, so branch 



TSC 






TCD 






PHA 






PHA 






PHA 






PHA 






_Rea 


dTj 


i meHex 


PLA 






PLA 






PLA 






PLA 






XBA 






AND 




*IQF 


DEC 




A 


CMP 




#7 


BCS 




D0W_Error 
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FE1 



FE2 



LDfl 


>DayTable,X 


BEQ 


FE2 


INX 




BRA 


FE1 


IN* 




INX 




DEY 




BRA 


F; ndEntr v 



(Force long because B<>K] 
Branch if at end of name 
Move to next character 



; Move to start of next name 
•jDecrement day-of-week counter 

{ Transfer the name to the buffer area: 

;Uae 8-bit accumulator 

;Branch if at end of name 



SaveResu 1 t 


SEP 


'120 






LONGA 


OFF 






LDY 


#1 


SR1 




LDA 


>DayTable,X 






BEQ 


SR2 






ST A 


[ThePtr] ,V 






INX 








INY 








BRA 


SRI 


SR2 




DEY 
TYA 








STA 


[ThePtr] 






REP 


#$20 






LONGA 


ON 






LDA 


#0 






BRA 


DOW.Exit 


DDW_ 


Error 


LDA 


#TS_NUM»256 


DDW_ 


.Exit 


TAX 
PLD 





; Store length of string 
;Back to 16-bit accumulator 

; No error 

; Error code #1 

;Save error code in X 

^Restore direct page 



*, Remove the long input parameter from the stack: 



LDA 


S,S 


STA 


9,5 


LDA 


3,S 


STA 


7,S 


LDA 


1,5 


STA 


5,5 


TSC 




CLC 




ADC 


M 


TCS 





;Move the two long JSL 
; return address up by 
; four bytes 



; Increment the SP by 
; four bytes. 



Using the CS Tools 



TXA ;Get error code 

CMP # t ;Set carry if error 

RTL 

MSB OFF 

DayTabLe DC C 'Sunday ', 1 2' Q » 

DC C'Monday 1 ,12»0' 

DC C'Tuesday' , 12'0« 

DC C'Wednesday' , I2'0 T 

DC C'Thursday' ,I2'0» 

DC C'Friday 1 ,I2'0' 

DC C Saturday' , I 2 ' ' 

END 
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CHAPTER 4 



Memory 
Management 



As discussed in chapter 2. the 65816 microprocessor that controls the gs can access 
directly an enormous 16-megabyte memory space (arranged as 256 memory banks 
of 64K each); the 24-bit memory addresses run from $000000 to $FFFFFF. This 
space can be made up of any combination of ROM, RAM, and memory-mapped I/O 
(soft switch) locations, but it need not be fully populated. In a computer system, 
the ROM holds a bare-bones operating-system program (sometimes called a system 
monitor) which loads a more elaborate operating system from disk when the system 
is turned on. It also usually contains a collection of subroutines that an application 
program can call to perform standard tasks, such as clearing the screen, reading the 
keyboard, and printing a character. RAM, of course, is where an application stored 
on disk is loaded and where data of any sort can be stored by an application or the 
operating system. 

This chapter investigates the special uses the gs makes of the memory in the 
65B16.S address space. Some clues concerning the operation of the GS will be 
uncovered, and you will discover which areas of RAM are available for use by your 
own applications. 

When writing an application for the gs (or any computer for that matter), it is 
important to avoid using memory areas already in use by the operating system or 
by any other application. If you overwrite busy memory areas, the system is sure 
to behave unpredictably. 

It is easy to write a program for the He that does not conflict with the original 
FroDOS 8 operating system. Pro DOS 8 occupies specific memory areas and pro- 
grammers are responsible enough not to use those areas for applications. Trying to 
live with another application in memory, such as a desk accessory utility, can be 
fatal, however. Why? Because no software protocol for informing an application of 
the memory other applications are occupying has been implemented, A co-resident 
desk accessory utility, such as the Pinpoint Desk Accessories, is useful only because 
it occupies an area Few applications use (the auxiliary bank-switched RAM area). 
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A program can avoid memory conflicts in a ProDOS 16 cs environment simply 
by using a tool set called the Memory Manager. When the program needs a block 
of memory to work with, it simply issues a request to the Memory Manager. The 
Memory Manager processes the request by locating a free area of memory of the 
proper size, marking it as in use, and returning its handle (the address of a pointer 
to it). As long as every program uses the Memory Manager, no program will tread 
on the toes ol any other program. 

The use of the Memory Manager is discussed at the end of this chapter. 

cs MEMORY MAP 

As shown in figure 4-1, the CS can address up to 256 banks of memory. The banks 
are numbered from $00 to $FF, and each one is 64 K in size. In its minimal 
configuration (no card in the memory expansion slot), the GS has 256K of RAM and 
L28K of ROM, so it uses only six of these banks: banks $00. $01, $E0, SE1. $FE, 
and $FF The first four of these banks hold the RAM, and banks fFE and $FF hold 
the ROM. The rest of the banks are unoccupied or unavailable, 

The RAM in banks SE0 and $E1 deserves special mention because it has one 
restrictive characteristic that the RAM in other banks does not: read and write 
operations affecting these banks always take place at the normal (1 MHz) clock- 
speed, even if the system speed is set to fast (2.8 MHz). 

If you are operating in fast mode and you start using either of these hanks, the 
cs hardware slows the system clown and automatically returns to fast mode when 
you are done, The reason for the slowdown is that banks SEO and $E1 contain video 
display buffers and other memory-mapped I/O locations that, for reasons of com- 
patibility with existing lie software and hardware, must he accessed at the same 
clock speed used by the lie ll MHz). 

Y mi can add more RAM to the CS by inserting an appropriate card in the memory 
expansion slot (see appendix 6), Additional RAM occupies consecutive banks begin- 
ning at bank $02 — if you add one megabyte of memory (sixteen 64K banks), for 
example, it will occupy banks $02 through SI L The upper limit for RAM expansion 
through the memory expansion slot is 8 megabytes, 

A memory expansion card may also contain ROM, The ROM may occupy any ol 

i $F0 to SFD The data in hanks SF0 to $F7 (a 512K space) is expected 

to be organized just as it would he on a disk; that is, these ROM banks are configured 

as a ROM Disk. The ROM in banks $F$ to SFD is designed to hold extensions to 

the firmware ROM. 

SPECIAL RAM AREAS 

Several areas in the tour core RAM banks ($00, $01, $E0, and $Eli are used for 
Special purposes, by the 65816, the operating system, the firmware, or I/O devices. 
Programs must respect this usage and not attempt to use these areas for other 
purposes, except where the context permits. 
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Figure 4-1. The Apple Has Memory Map (Each RAM b ank is 64K in size. ) 
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Banks $E0 and $E1 

The two RAM banks in the high end ol memory, banks $E0 and $E1, are often 
referred to as the firmware RAM because the ROM drivers for peripheral devices. 
such as the serial ports, the mouse, and the disk, use these banks for data storage. 
The System Loader (the portion of the operating system that loads Pro DOS 16 
applications), AppleTalk, and tool sets also make extensive use of the firmware 
RAM. As mentioned earlier, reads and writes to hanks SE0/SE1 always take place 
at 1 MHz, even if the system clock speed is set to 2.8 MHz. 

The lenient and use of memory in firmware RAM on the CS is, in many 

respects, the same as on the lie. Bank .SEO looks much like main memory on the 
He and bank $E1 looks much like auxiliary memory. The similarities are reviewed 
below, 

Language Card. The space from SDOOO to SFFFF (12K in size) in either of the 
two banks of firmware RAM is called a language card (or bank-switched RAM) and 
can be associated with either 12K of ROM or 16K of RAM. A program can switch 
between ROM and RAM on the fly by manipulating a set of software -control I able 
switches (called soft- -suit ches), 

The ROM for the language card is actually physically located in bank $FF (at the 
same relative position within the bank), but this area also maps to banks SEO and 
SE1 when the cs is turned on. The ROM contains Applesoft, the system monitor, 
I/O drivers, tool sets, and more. 

The RAM for the language card actually takes up 4K more space than what is 
available! The extra 4K is treated as a second §DOO0-$DFFF memory segment and 
soft switches are available to select which of these two banks is to be active. On the 
CS, the language card RAM in banks $E0/SE1 is reserved for use by the ProDOS 
System Loader and by AppleTalk. 

HO Space. The I/O space runs from $C0O0 to SCFFF. The first part of it, from 
$CO00 to SCOFF, is actually made up of memory-mapped I/O locations — that is. 
locations that can be read from or written to so that you can communicate with I/O 
devices. Each slot (or built-in port) has the exclusive use of sixteen unique I/O 
locations: $C090-$C09F for slot I, SC0AO-SC0AF for slot 2, and so on up to $COFO- 
$COFF for slot 7. The I/O locations from SCOOO to $C07F control internal I/O 
devices (such as the keyboard and the video) and modes of operation (including 
memory scire! inn, system speed, and graphics mode selection). 

Peripheral RO^f. The locations from $CnOO-$CnFF (n=l to 7) are reserved far 
ROM found on a peripheral card plugged into slot it. (Internal ports have ROM 
associated with them, too. It is stored in the lower part of bank SFF but is also 
mapped to the SCnv\ pages in banks SEO and $El.l A typical ROM contains a 
program that provides the subroutines a program needs to communicate easily with 
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a peripheral device. Each peripheral may also contain a 2K ROM area that occupies 
$C800-SCFFF; the peripheral can select this ROM area to the exclusion of all 

others. 

While a program is running in the peripheral ROM area, the cs always operates 
at normal speed (1 MHz). This is done to permit timing-sensitive peripherals 
designed for the He to work properly on the GS. For example-, an internal modem 
card like the Hayes Micromodem will not work at a clock speed other than 1 MHz 
because the program in its ROM that dials the telephone uses precise timing loops 
that are based on a 1 MHz clock speed. 

Video Buffers, The video buffers for the standard He video display modes — 40- 
and 80-column text, single- and double-width low-resolution and high-resolution 
graphics — are located in the same relative positions on the GS as on the lie: 

S400-$7FF are used for the page 1 40-column text display and low- resolution 
graphics modes 

$800-SBFF are used for the page 2 40-column text display and low-resolution 
graphics modes 

$2000-$3FFF are used for the page 1 high-resolution graphics mode 

8400O-S5FFF are used for the page 2 high-resolution graphics mode 

In each case, the standard text and graphics modes (40-column text and single-width 
graphics) use areas in hank SEO only. For 80-column text and double-width graphics 
modes, the same areas in bank $EI are also used. 

Other Special Areas. Another display mode, called super high-resolution graphics, 
has a video buffer located from $2000 to S9FFF in bank SE1 only. This is the display 
buffer used by the QuickDraw II graphic drawing tool set that is stored in the GS 
ROM. It docs not exist on the lie. 

The other areas in banks $E0 and SE1 that have special significance are the 
spaces from $0000 to $1FFF in both banks (which include the video buffers from 
$400 to SBFF that were discussed). These spaces are reserved by the operating 
system for the storage of variables, vectors, jump tables, and other data used by the 
GS tools and built-in I/O ports. 

Free Areas. The areas in banks $E0/$E1 not used for special purposes are; 

• S6000-$BFFF in bank $E0 
. $A000-$BFFF in bank $E1 
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These areas are free for allocation by the Memory Manager. Keep in mind that, jar 
all practical purposes, the video buffers used by page I and page 2 of standard high- 
resolution graphics ($2000-$5FFK in bank $E0» are also available if a program uses 
only the super high-resolution graphics mode. 

Banks $00 and $01 

Bank $00 is of particular importance, because this is where the 65816 locates its 
stack and direct page. In emulation mode, the stack occupies page $01 and the 
direct page Occupies page $00, In native mode, however, the operating system can 
position the stack and direct page anywhere in bank $00. 

One of the primary design constraints for the as was that it work properly with 
existing lie software (and hardware), To allow this, it was necessary to permit the 
remapping of banks $00 and $0] so that these areas could be used as the main and 
auxiliary memory areas are on the IIe T complete with an I/O space and a language 
card area. At the same lime, I/O and video operations had to take place at the same 
clock speed as the lie, namely I MHz. 

One way to accomplish this might have been to force banks $00 and $01 to 
operate at 1 MHz all the lime and to keep the standard video buffers and memory- 
mapped I/O locations in those banks. This would mean, however, thai one especially 
common 65816 operation— pushing data on the stack (a bank $00 operation)— would 
always cause the system to slow down, severely restricting the advantage of operating 
the cs in 65816 native mode at 2.8 MHz. 

The ultimate solution was not to restrict the speed of bank $00 and $01 operations 
to I MHz. Rather, the system was designed to detect automatically a write operation 
to a video buffer or the I/O space (at a speed of 2.8 MHz or 1 MHz) arid to generate 
a concurrent write operation (always at 1 MHz) to the same location in bank SE0 
(fOT bank $00 writes) or bank $E1 (lor bank S01 writes). This technique is called 
Shadowing. Heading from a shadowed video buffer does not cause (he system to 
slow down because neither bank $E0 nor bank $E1 is accessed. 

The areas in hanks $00 and $01 that may be shadowed are shown in figure -1-2. 
The cs has a shadow register that controls which video buffers are actually shadowed 
at any given time (see figure 4-3). A bit in the shadow register also controls the 
shadowing d I/O locations and language card operation. 

Notice that the page 2 text and low-resolution graphics screen cannot he shadowed 
using hardware techniques, but it is rarely used anyway. (A software technique 
wherein data in bank S00/$0J is transferred to bank SE0/$E 1 in response to a periodic 
interrupt car, he implemented to emulate hardware shadowing. Invoke this by 
setting Alternate Display Mode On from the desk accessory menu.) 

II shadowing is inhibited, a program must directly access the video buffers or I/O 
locations in bank $E0 or *E1. Enabline I/O shadowing also creates a language card 
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Figure 4-2. The Shadowed Memory Areas on the Apple lies 
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at J5D000-SFFFF in hanks $00/$01 dial works just as the one in the He does (see 
the description above for banks IEWE1). This, in turn, enables access to the 
Applesoft and system monitor ROMs, 

In normal Apple lie emulation mode, all video areas are shadowed SO that all 
existing software will work properly. When the GS*S new super high-resolution 
graphics .node is used, shadowing of other graphics modes is disabled so that the 
shadowed space in banks $E0 can be freed. 
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Figure 4-3. Tin Shadow IV 
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In normal operation, the t;s always enables shadowing of the text pages, even if the 
texl screen is not used. Tins is necessary so that lie-style peripheral cards (which 
write to unused areas of the text display buffer) will work properly. Also, IAD 
shadowing is enabled so thai Interrupts [which vector through ROM in bank $00) 
can be handled. 



EXPANSION RAM 

Banks $02 through $DF (14 megabytes less 128K) are all reserved for future RAM 
expansion, although Apple has imposed a practical limit of 8 megabytes by not 
providing decoding circuitry beyond the S-megabyte limit. Any expansion RAM you 
add is available for allocation with the Memory Manager. 
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Figure 4-4. The CYA ("Configure Your Apple") Register 
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Video and I/O shadowing can be permitted for all of these banks as a group {but 
not individually) by setting a bit in the CYA register (see figure 4—4). Even-num- 
bered banks shadow to page SEO and odd-numbered banks to page $E1. However, 
you should never shadow expansion RAM if you are running GS-style applications 
because they will not run properly. The problems begin when the Memory Manager 
allocates space somewhere in the language card area of a bank, an area where ROM 
is usually enabled (just as it is in banks $00/$01). When a tool or a program tries to 
write to the allocated space, nothing is saved! 

Refer to appendix 6 for descriptions of several memory expansion cards available 
for the cs. 

THE ROM BANKS 

The 128K ROM in banks $FE and SFF contains the ROM versions of many of the 
GS too] sets and desk accessory support code. It also contains, from $8000 to SFFFF 
in bank SFF, a system monitor comparable to that found on the lie, the Applesoft 
BASIC programming language, and subroutines to support the built-in peripheral 
devices on the CS. By using clever hardware remapping techniques, the upper 12K 
of bank SFF can be used as if it occupied the same portion of bank $E0. SE1, or 
any other bank for which I/O shadowing is enabled. 
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The fourteen banks from $F0 to $FD are reserved for future ROM expansion. 
Banks $F0 through SF7 (512K) are to be used as a ROM disk and banks $F8 through 
■$FD (384K) are for additional firmware ROM. 



THE MEMORY MANAGER 

The Memory Manager is tool set #2. The main chore it performs is allocating areas 
of memory in such a way that previously allocated areas are not disturbed. Its other 
major chore is releasing allocated areas of memory to the general pool of available 
memory. 

The Memory Manager manages all of RAM memory except the following areas; 

• $CQOQ-$FFFF in banks $00. $01, $E0, $El 

• $0000-$07FF in banks $00, S01 

• $00O0-$lFFF in banks SE0, $E1 

unmanaged areas are reserved for use by the operating system. 

Areas of memory allocated by the Memory Manager are called blocks, Each block 
is identified by a four-byte address, called a handle, which is returned by the 
function performing the allocation. It is important to realize, however, that the 
handle is not the address of the block itself— ins Lead, it is the address of a 20-byte 
block record. The first entry in this record is a pointer to the block {called a master 
Per); it is the master pointer that contains the address of the block. See figure 
4-5 for a pictorial representation of the relationship between a handle, a block 
record, a master pointer, and the block itself. 

The advantage of using a handle instead of a pointer to identify a block is that a 
handle to a block remains valid even if the block is repositioned by the Memory 
Manager — only the address stored in the master pointer changes. If a pointer was 
returned instead, and the block was moved, a program would not be able to 
determine the address to which the block was moved. 

The Memory Manager moves blocks around when it needs to perform a block- 
coin paction operation. This occurs in only two situations: when you specifically 
request it (with CompaetMem), or when you try to allocate a block (with New- 
Handle, ReallocHandlc, or Restorellandle) and there is no free area large enough 
to hold it. Block compaction gathers together allocated blocks which may be scat- 
tered throughout memory. This is done to eliminate gaps between blocks and to 
create as large a continuous free space as possible. Scattering occurs as blocks are 
allocated and deallocated during program execution. 

If you are trying to allocate a block and there is no room for it even after 
compaction, the Memory Manager automatically frees purge-level-3 blocks (the 
Purge Level attribute is discussed below) and trie blocks are compacted again. If 
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Figure 4-£, Block Allocation with the Memory Manager 
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there still is not enough room, purge-level-2 blocks and then puree -level- 1 blocks 
are freed; further compactions occur until there is room. An out-of- memory error 
is reported if there is no room even after all three levels of purgeable blocks have 
been purged. 

You can tell the Memory Manager to free (or dispose of) previously allocated 
blocks by using the DisposeHandle function. It is good programming practice lo 
dispose of blocks as soon as they are no longer needed so that as much space as 
possible ij. always available- 
Attributes 

When you make a block allocation request (with XewHandle or RealloeHamllK 
you must tell the Memory Manager the attributes of die block These attributes 
indicate where the block is to be allocated and how it is to be dealt with alter 
allocation. 
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Figure 4-6. The Attribute Word for a Block 



1514131211109 8 7 6 5 4 3 2 10 



T 



.. ^ . 



reserved 
(must be 0) 



T 



reserved 



I = fixed bank 

1 = fixed-address 

I = page aligned 

I = special memory 
not usable 

■ 1 = bank-boundary 

limited 

■ purge level (0 to 3) 
1 = fixed 

■ 1 = locked 



The attributes are passed in a word; the bits in this word have the meanings shown 
in figure 4-6. Note that except for the Locked and Purge Level attributes, none of 
the attributes can be changed with function calls after the block has been allocated. 

Locked. A locked block is one the Memory Manager is not permitted to move, 
even if the Fixed and Fixed Address attribute bits are off. In addition, a locked 
block cannot lie purged even if its Purge Level is non-zero. 

The Locked attribute can be changed after a block is allocated by calling HLock 
(to turn it on) or HUnLock (to turn it off). You should lock a block only when 
necessary, such as when you need to access the data it contains (see below), and 
then unlock it as soon as you can. Because locked blocks cannot be moved, they 
can prevent efficient block compaction operations and can lead to premature out- 
of memory errors. 

Fixed- Like a locked block, a fixed block may not be moved by the Memory 
Manager during a memory compaction operation; it stays put. The main difference 
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between a fixed block and a locked block is that a fixed block tan be purged if its 
Purge Level is nun-zero. In addition, the setting of the Fixed attribute cannot be 
changed with a function call. 

Purge Level. Purging a block means releasing a block by setting its master pointer 
to (the space lor the block record containing the master pointer is maintained and 
can be reused by calling ReallocHandle or RestorcHandle). The purged block returns 
to the pool of free memory that is available for future allocation by the Memory 
Manager, but the handle itself remains allocated and can be reused. 

The Purge Level of a block can be 0, 1, 2, or 3, numbers that re flee I the purge 
priority: blocks with higher purge levels are purged before blocks with lower purge 
levels, A Purge Level of means that the block cannot be purged at all. The Purge 
Level <'l a block can be changed after allocation with the SetPurge function. 

Purge level 3 is reserved h>r use by the G5 System Loader, the tool set responsible 
for dealing with ProDOS 16 load files (which usually contain programs). When the 
System Loader loads a program, it first puts the previous program into a dormant 
(or "zombie \ State by assigning a purge level ol 3 to the memory blocks it uses. If 
any of these blocks are purged, they are all purged; if no purging takes place and 
control returns to the program, however, the System Loader does, not reload the 
program from disk, it just sets the purge level ol the block to zero and executes the 
program. 

You can purge purgeable. unlocked memory blocks explicitly using PurgeHandle. 
Purging also occurs automatically if you call NewHandle, ReallocIIandie. or 
RestoreHandle and there is not enough space for the new block even after the 
blocks are compacted, in this sit nation, purgeable blocks are purged, in priority 
order, until there is enough space. 

Bank-Boundary Limited. If a block is Bank-Boundary Limited, it will be allocated 
in a single bank- Blocks that contain program code must have this attribute set, 
because 65IS16 programs cannot cross bank boundaries. (When the program counter 
goes from $FFFF to $0000 at a bank boundary, the carry generated is ignored and 
is nut added to the program bank register. That means execution continues at the 
bottom of the current bank, not at the bottom of the next bank, as might be 
expected.) 

Ordinary data blocks may span banks, however, because the 65816 indexed 
addressing modes let you index properly from one bank to the next. 

Special Memory Sot Usable. If this attribute is set. the block may not be allocated 
in bank $00 or $01. or in any of the graphics video buffer areas in banks $E0 or SE1 
($20OO-$5FFF in $E0 and $2000-$9FFF in bank $E1). You would set this attribute 
if you were reserving memory from a He-style application so as to avoid allocating 
areas in the 12SK program space. 
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Page- Aligned. If the block is Page- Aligned, it begins at an address of the form 
$bbxxOO, that is, at the beginning of a memory page. (A memory page is the 256 
bytes extending from address SbbxxOO to ShbxxFF.} You should set this attribute 
when allocating space to be used as a 65816 direct page so as to maximize the speed 
of direct page operations, A direct page operation still works if the page is not 
aligned, but it takes one cycle longer to execute than if It is aligned. 

Fixed Address. Set this attribute if you want a block to be allocated at a specific 
location in memory, You might want to do this. For instance, to align a block with 
one of the graphics screen video buffers. The GS operating system uses this attribute 
when it reserves specific memory areas at start-up time. 

Fired Bank. If the Fixed Bank attribute is on, the Memory Manager will al- 
locate a block in the bank specified when you eaJl NcwrJaudle. Realloe Handle, or 
RestorcHandle. You must set this attribute when allocating direct page and stack 
space, because the 65816's direct page and stack must be in bank $00. 

Accessing a Block 

To read data from or write data to a block, you need to know the address of the 
block. To get it, you must first dereference the handle to the block to determine 
what the master pointer is Then, you can address the block by storing the master 
pointer in direct page and using the [dp],Y indirect addressing mode. (Recall from 
chapter 2 that the brackets indicate that this is a long addressing mode, not a short 
addressing mode: the pointer to the start of the block is stored at dp, dp+.l, and 
dp +2, where dp is a direct page address.) 

In the example to follow, a 256- byte block, whose handle is stored at MyHandlc, 
is filled with zeroes. The first part of the .subroutine dereferences the handle 
{DPScratch and To Block are the direct page addresses of two four-byte areas,): 

\ 1 6-bi t A register 

LDA MyHandle *,Put handle in direct page 

STA DPScratch \ so that the master pointer 

LDA PTyHandle + 2 ; can be accessed with an 

STA DPScratch+2 ; indirect long addr mode. 

;Get master pointer (low) 
;Get master pointer (high) 



LDA 


[DPScratch] 


STA 


ToBloc k 


LDY 


#2 


LDA 


[DPScratch! ,Y 


STA 


ToBlock+2 


LDY 


#0 


LDA 


#0 
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ClearBlk 


STA 
INY 
INV 


(ToBlock J,Y 




CPY 


#256 




BNE 


ClearBlk 




RTS 





; Store a zero 



-.Branch unti 1 Y-2S6 



An important caveat: You cannot use a dereferenced handle to access a block if the 
block may have been moved (because of compaction) or purged by the Memory 
Manager since the time you did the dereferencing — it may not point to the block 
anymore. Compaction and purging can occur if you call the Memory Manager 
directly, if you call a tool set function that calls the Memory Manager or even il an 
interrupt occurs (the interrupt handler could call the Memory Manager), 

To prevent the movement or purging of a block — and to maintain the validity of 
a dereferenced handle — lock the block in place with the HLock function just before 
you dereference. If you do this, be sure to unlock the block {with HUnLock) when 
you are through using the dereferenced handle. The alternative is to avoid calling 
tool set functions which may use the Memory Manager and to disable interrupts, 
restrictions which are usually impractical, 

IF you choose not to lock the block, you should dereference the handle to the 
block even' time you want to access the blocks data, but even this may not work il 
interrupts are occurring. 

Of course, you do not have to worry about locking a block (or unlocking it) if you 
set the Fixed or Fixed Address attribute when the block was first allocated (and the 
block is not purgeable) or if you set the Locked attribute. 



MEMORY MANAGER FUNCTIONS 

There are many memory manager functions at your disposal, but most applications 
will use only a core group of six major functions. This chapter looks at this core 
group and then reviews most of the minor functions. (See table R4-1 at the end of 
this chapter for a summary of the major memory manager functions.) 

The Major Functions 

Start-up and Shut-Down. Like all tool sets, the Memory Manager has a start-up 
function. MMStartup, that your application must call before it can use the Memory 
Manager. Because almost every other tool set implicitly uses the Memory- Manager, 
you must call MMStartup before calling the startup function of any other tool set 
except the Tool Locator and the Miscellaneous Tool Set. 

MMStartup takes no input parameters, but it does return a result- — an Owner 
ID tag. The ID tag is an identification code assigned to the program when the 
System Loader loads it into memory prior to execution. It is to be used to mark all 
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blocks allocated by the application. It also identifies the blocks to be included in 
certain group operations the Memory Manager can perform. 
Here is how to call MM Startup: 

PHA ; Space for result (word) 

_MM5tartup 

PL A 

STA MylD ;Save ID code 

MylD is a two-byte data area that can be allocated with a data allocation directive 
of the form: 

MylD DS 2 ;Allocate two bytes 

You should save MylD. because you will need it to start up other tool sets, 

MM Shu I Down is the shut-down function for the Memory Manager, Call it just 
before the application ends, after shutting down all other tool sets (except the Tool 
Locator and the Miscellaneous Tool Set). MMShutDown has one input parameter 
(the ID tag returned by MM Startup) and returns no results: 

PushWord MylD 
.MMShutDown 

Note that MMShutDown does not free up all memory blocks associated with MylD 
This is done by Pro DOS 16 when it regains control after a ProDOS 16 QUIT 
command. You can explicitly free up memory blocks with the DisposeHandlc func- 
tion (see below). 

Block Allocation. NcwHandle is the primary block allocation function, With it 
you can create blocks of any size, with any attributes, and you can associate them 
with any ID tag. NcwHandle returns a handle to the allocated block. 
The general calling sequence looks like this: 

PHA ;5pace for reault (long) 

PHA 

Pu5hLong BioekSwe jSiie of block 

PushWord DwnerlD ;Dwner ID tag 

PushUlord Attributes ;Attribute5 of block 

PushLofig Location ;Address of block 

_NewHandle 

PopLong MyHandle »Pop handle to block 

(Recall from chapters 2 and 3 that PushWord, PushLong, and PopLong are macros, 
not 65816 instructions.) 

BlockSi/e is the size of the block to be created, in bytes, Owner! D is the ID 
code to be assigned to the block and is normally the same as the ID code returned 
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by MM Startup, Attributes is the attribute word for the block. Location is the starting 
address of the block and is meaningful only it the Fixed Address or Fixed Bank 
attribute is set. 

NewHandle does all it can to reserve the requested space, including block 
compaction and purging. If necessary, The handle that is returned points to a block 
record made up of the following elements: 

• Address of block (4 bytes) 

• Block attributes (2 bytes) 

• Owner ID tag (2 bytes) 

• Size of block (4 bytes) 

• Address of previous block record (4 bytes) 

• Address of next block record (4 bytes] 

If the record is the firsi or last one in the list maintained by the Memory Manager, 
the pointer to the previous block record or to the next block record is zero. 

Notice that in the previous example, BtackSize, Attributes, and Location arc- 
passed as variables (numbers stored in memory locations), even though you are 
probably more likely Id pass them as constants (immediate values). To pass constants, 
precede the constant with "#" to inform the PushLong or Push Word macro that it 
is a constant. For instance, to allocate five pages of memory in bank $00 for possible 
use as direct pages by other tools, call NewHandle like this. 

PHA ;Space for result (long) 

PHA 

PushLong #$500 ;Five pages (ISQQ bytes) 

PushWord My I D ; 1 D returned by MMStartup 

PushWord #*C005 ;Loeked, Fixed, Fixed Bank, Aligned 

PushLong #0 jAddress: bank 100 

_HewHa nd 1 e 

PopLong MyHandle ;Pop handle to block 

Notice the attribute word for this block: SC0O5. Because a direct page must be in 
hank S0O, the Fixed Bank attribute (bit 0) is set. Because 65816 direct page instruc- 
tions work more quickly when direct page begins on a page boundary, the Page 
Aligned attribute (bit 2) is also set. The Locked attribute (bit 15) is set so that the 
block will not move around — this means that you will have to dereference its handle 
only once to access it. Finally, the Fixed attribute (bit 14) is set so that the block 
will not move even il it is accidentally unlocked 
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Block Deallocation, As soon as you arc finished with a previously allocated block 
of memory, you should Free it up again to eliminate the possibility oi ait early out- 
of-memory error. To do this you ran use the DisposeHandle function: 

PuahLong MyHandle -.Handle to block 

_Di sposeHandle 

DisposeHandle also removes the entry for the master pointer in the Memory 
Manager's list of master pointers. This means that you cannot reuse the handle with 
Kcalloc Handle or Restore Handle. 

DisposeHandle does its duties even if the block is locked or not purgcable. 

Locking and Unlocking Blocks. As mentioned earlier, it is important to loek a 
moveable or purgcable block to ensure its dereferenced handle remains valid for 
data accesses. The Function for doing; this is 11 Lock: 

PushLong MyHandle ;Handle to block 

_HLock 

The function lor unlocking a block is _HUnLock. It also takes a handle to the block- 
as its only parameter. 

The Minor Functions 

Most applications will not need to use the remaining Memory Manager functions 
vers often — they are used primarily by the operating system Nevertheless, it is 
important to become familiar with them so that vou will recognize how to handle 
those situations calling for their use. 

Reallocation of Purged Blocks. If a block has been purged, its master pointer is 
set to 0, but the space occupied by the master pointer is not freed. To reuse the 
mister pointer of a purged block, call ReallocElaiKlle. It behaves just as NcwHandle 
does except that it requires one additional parameter, the handle to the purged 
block. This is the last parameter passed; the other parameters are pushed first in 
the same order as for New Handle. You may find it simpler to use ReStoreHandle, 
It needs only the handle, the file attributes, owner, and size previously used are 
retained. 

When allocating space for a purged block, you should resist the temptation to 
use New Handle. If you do not reuse purged handles, you will waste memory (20 
bytes per handle, the size of the block record) and Memory Manager operations 
will be a bit slower. 

Disposing and Purging Blocks. We saw earlier that DisposeHandle frees only the 
block associated with a particular handle. With DisposeAll, you can free up a group 
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of blocks at once, each associated with the same ID tag. To use Dispose All, pass 
the ID tag as a parameter: 

PushWord Owner ID ; I D tag 

_DisposeA 1 1 

This example disposes of all blocks associated with Owner! D, Do not try to dispose 
of all blocks marked with the ID of the program itself, because the memory the 
program occupies could be overwritten before the program ends. 

Another way to free up space is to purge a block or group of blocks with 
Purgellandle or PurgeAll. Both functions will purge any unlocked block, even if 
the block's purge level is 0. The inpul parameter for PurgeHandle is a handle to 
the block to be purged. The parameter for PurgeAll is an ID tag — all blocks with 
the specified ID are purged. 

Setting Attributes. Only the Locked and Purge Level attributes of a block can be 

modified after the block has been allocated. HLock and HUnLock, which lock and 
unlock individual blocks, have already been discussed. Two other functions, 
HLockAll and HUnLockAll, lock and unlock a group of blocks with the same ID 
tag. Pass the ID tag on the stack before calling either of these functions. 

To set the purge level of a block, use SetPurge. It takes two parameters: the new 
purge level (a word from to 3) and a handle to the block: 

PushWord #1 ■, Purge Level = 1 

PuahLong MyHandle ; Handle to block 

_Set Purge 

SetPurgeAll sets the purge level of ever)' block with a given ID tag. The two 
parameters it requires are the new purge level and the ID tag. 

Black Information Functions. Findllandle takes a memory location as an input 
parameter and returns a handle to the block in which it is located. For instance, a 
program can deduce the handle to the block in which it is currently running by 
executing the following segment of code: 

PHA ;Space for result (handle) 

PHA 

PushP'tr MyLabel -.Push long address 

MyLabel _FindHandle 

PopLong CodeHndl ;Pop the result (handle) 

Get Handle Size takes a handle as an input parameter and returns the size of the 
block to which it refers. To get the size of the code segment in the above example, 
use the following code: 
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PHA -,Space for result (long) 

PHA 

PushLong CodeHndl ;Handle to code block 

JjetHandleSaze 

Poplong Size ;Pop the result (long) 

Use SetHandleSize to expand or contract the size of an existing block. The input 
parameters are a handle to the block and the new size of the block (a long word). 
For example, suppose your code block has an initialization sequence 743 bytes long 
which is located at the very end of the block. If you expect to be tight on memory 
space, you may want to dispose of it after you are through with it. Here is how you 
can do that: 

PushLong CodeHndl ;Puah handle to code block 

SEC 

LDA Size ;New size = old size 

SBC #743 l minus 743. 

PHA 

LDA Size+2 

SBC #0 

PHA 
SetHandleSize 



Data Movement. The Memory Manager has four functions that permit you to 
move a block of data from anywhere in memory to anywhere else in memory. All 
you need is a pointer or handle to the start of the source block and to the destination 
block. If you use a handle, the Memory Manager function takes care of dereferencing 
it. 

Here is a summary of how each of the four data movement functions work: 

PtrtoHand Move a block referenced by a pointer to a block referenced by 

a handle 
HandtoPtr Move a block referenced by a handle to a block referenced by 

a pointer 
HandtoHand Move a block referenced by a handle to a block referenced by 

a handle 
BlockMove Move a block referenced by a pointer to a block referenced by 

a pointer 

Each function requires three long-word parameters on the stack, 1 a pointer or handle 
to the source block, a pointer or handle to the destination block, and a count of the 
number of bytes to move. 
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Be very careful when using the data movement Eunctkms. They do not verify the 
validity of handles and pointers, and they do not check to see if the destination 
block is large enough to accommodate the transfer 

Free Space Functions. Three Memory Manager functions return numbers reflect- 
ing the sizes of various spaces in the system; 

FreeMem returns the number of free bytes in memory. The number does not 
include the space occupied by purgeable blocks. FreeMem does not compact 
memory. 

MaxBlock returns the size of the largest free block in memory. MaxBlock does 
not compact memory and it does not purge purgeable blocks. The number 
returned by MaxBlock cannot exceed the one returned by FreeMem because 
of block fragmentation, 

TotalMem returns the size of the 11AM space in the system. 

None of these functions takes input parameters, and all three functions return a 
long word (the size in bytes). 



REFERENCE SECTION 

Table R4-1: The Major Functions in the Memory- Manager Tool Set ($02) 





Function 


Stack 


Description of 


Function Name 


Number 


Parameters 


Parameter 


BlockMove 


S2B 


SourcePtr (L) 


Pointer to source block 






DestPtr (L) 


Pointer to destination block 






Count (L) 


Number of bytes to copy 


CheckHandle 


S1E 


TheHandle (L) 


Handle to be validated (*) 


CornpactMem 


$1F 


[no parameters] 




DisposeAll 


$11 


UserlD (W) 


ID tag for blocks to dispose 


DisposeHandle 


$10 


TheHandle (L) 


Handle to block to dispose 


FindHandle 


$1A 


result (L) 


Handle for block 






VI e m Location ( L) 


Location to test 


FreeMem 


SIB 


result (L) 


Amount of free memory 
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Function Name 


Function 
Number 


Stack 
Parameters 


Description of 
Parameter 


GetHandleSize 


SIS 


result (L) 


Size of block in bytes 






The Handle (L) 


Handle to block 


Handtolland 


$2A 


SourceHndl (L) 


Handle to source block 






DestHndl (L) 


Handle to destination block 






Count (L) 


Number of bytes to copy- 


HaudtoPtr 


S29 


SourceHndl (L> 


Handle to source block 






DestPtr i L: 


Pointer to destination block 






Count (LJ 


Number of bytes to copy 


H Lock 


$20 


HieHandle (L) 


Handle to block to lock 


HLockAll 


$21 


UserlD (W) 


ID tag of blocks to lock- 


H In Lock 


S22 


Thellandle(L) 


Handle to block to unlock 


HUnLoekAl] 


$23 


UscrlD(W) 


ID tag for blocks to unlock 


Max Block 


$1C 


result (L) 


Size of largest free block 


MMShutDown 


$03 


IserlD(W) 


ID tag returned by 

MM Startup 


MM Startup 


$02 


result (W) 


ID tag for memory 

allocation 


NewHandle 


S09 


result (L) 


Handle to new memory 
block 






BlockSize (L) 


Size of memory' block 






UserlD (W) 


ID tag lor memory block 






MemAttrib (W) 


Attributes of memory block- 






Mem Location 1,; 


Allocation address 


PtrtoHand 


$23 


Source Ptr (L) 


Pointer to source block- 






DestHndl (L) 


Handle to destination block 






Count (L) 


Number of bytes to copy 
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Function Name 


Function 

Number 


Stack 

Parameters 


Description of 
Parameter 


Purge All 


|13 


UscrlD(W) 


ID tag for blocks to purge 


PurgcHandle 


$12 


The Handle (L) 


Handle to purge 


Realloc Handle 


$0A 


BlockSizc (L) 


Size of memory block 






UserlD(W) 


ID tag for memory block 






MemAttrib (W) 


Attributes of memory block 






MemLocatiun (L) 


Allocation address 






Thellandle (L) 


Handle to re-use 


Restore Handle 


SOB 


Tin: Handle (L) 


Handle to be restored 


Set Handle Size 


SI9 


NewSize (L) 


New size oi block 






Tht- Handle (L) 


Handle to block to be 
resized 


SetPurge 


$24 


Purge Level (W) 


New purge level 






TheHandle(L) 


Handle to memory block 


SetFurgcAll 


$25 


Purge Level (W) 


New purge level for blocks 






UserlD (W) 


ID lag for blocks involved 


TotalMem 


$1D 


result (L) 


System memory size 


* For Check Handle, 


an ei rw code 


of $0206 is returned if the handle is not valid. 



Table R4-2; Memory Manager Error Codes 



Error Code Description of Error Con dition 



$0201 Out of memory; the block was not allocated 

$0202 The operation failed because the* block has been purged. 
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Error Code Description of Error Condition 



$0203 An attempt was made to reallocate (with Real loc Handle) a handle of 
a block that has not been purged yet. 

$0204 The operation failed because the block is locked or immovable. 

$0205 An attempt was made to purge an unpurgeable block. 

$0206 The handle does not exist. 

S0207 The ID tag does not exist. 

$0208 Illegal operation on a block with the specified attributes. 
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CHAPTER 5 



Event 
Management 



An important part of any application program is the code that checks for user input 
and responds to it in an appropriate way. The two main sources of user input on 
the cs are the keyboard and the mouse, but incoming data can also come from any 
other device on the Apple DeskTop Bus or from a device connected to a port or 
slot. The occurrence of a discrete element of input activity is called an event and 
the tool set an application uses to monitor events is called the Event Manager. 

The Event Manager actually handles more than just traditional mouse and key- 
board events. It also manages two window-related operations that take place when 
the appearance of a window on the graphics screen is to be changed — namely, 
activate/deactivate events and update events. (Windows will be discussed in detail 
in the next chapter.) The cs operating system treats activate/deactivate and update 
activities as events to make it easier to develop software working in a multiwindow 
environment. 

THE EVENT LOOP 

Any CS application that uses the desktop environment should be event-driven. That 
is, the application should be ready, at all times, to react to any event which might 
occur. It should avoid putting the user in a mode that restricts the group of actions 
the user may perform , because this only serves to Frustrate the user. Ol course, 
there are times when restrictive modes are desirable, such as when the application 
wants to force the user to respond to an important question before proceeding 
further, but such modes arc not needed often. 

An event-driven application spends most of its time in an event loop, in which 
it repeatedly checks for the occurrence of an event. When an event occurs, the 
application responds to it and then returns to the loop and waits for the next event. 
Here is the simplified flowchart of an event-driven application: 
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As you can see, the main ta.sk of an event loop is to check whether an event has 
Occurred. This is a very simple task involving the use of the Event Manager's 
GetNextEvent function. The actual handling of an event is more complicated but 
still quite straightforward The most difficult part of any application, of course, is 
the part actually performing the tasks selected In the user. 



Initializing the Event Manager 

Chapter 3 explained that before you can use any tool set you must initialize it by 
calling its start-up function. The name of the start-up Function for the Event Manager 
is EM Startup. Call it right after starting up the Tool Locator and the Memory 
Manager with calls to TLStartup and MMStartup. 
The calling sequence for F.M Startup looks like this: 



PuahWord DPAddr 

PushWord #OueueSize 

PushWord fXMjnClamp 

PushWord #XMaxClamp 



;0ne page in bank $00 
;Size of event queue 
;Mou5e minimum (horiz) 
;Mouse maximum (horiz) 
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PushWord #YMinCLamp ;Mouse minimum (vert) 

PushWord #YMaxClainp ;Mouse maximum (vert) 

PushWord UserlD ;ID returned by MMStartup 
_EMStar tup 

EM Startup docs not return a result. 

DPAddr is the starting address of a 256-byte area in bank $00 that the Event 
Manager uses as a direct page. EM Startup puts this address in the Work Area 
Pointer table using the Tool Locator's SetWAP function U se the Memory Managers 
NevvHandle call to allocate the bank S00 space: 

PHA ;Space for result 

PHA 

PushLong #256 ; Need one page (256 by tea) 

PushWord UaerlD ; ID returned by MMStartup 

PushWord #SCQQ5 ;Locked, Static, Fixed Bank, Aligned 

PushLong #1000000 ;Addre55: bank 100 

_NewHand la 

PopLong MyHandle ;Pop handle to block 

To determine the actual direct page address to be used as DPAddr, you must first 
dereference the handle using the techniques described in the last chapter. The 
address is the low-order word of the dereferenced handle. 

QueueSize is the number of events the Event Manager can keep track of at one 
time. The events are posted in a queue as they are detected and are removed one 
at a time as the application calls GetNextEvent. If the application does not retrieve 
events from the queue often enough, the queue could fill up, causing older events 
to be lost as they are replaced by more recent events. QueueSize must be an integer 
between and 3539, If a value of is specified, a default size of 20 is used; this is 
a suitable size for most applications, 

The four clamp parameters describe the coordinates of the rectangle in which 
the mouse pointer will be confined on the screen XMinCkunp and XMaxClamp 
refef to the left and right sides of the rectangle, and YMinClamp and YMaxClamp 
refer to the top and bottom sides. The clamp parameters are usually set to the 
coordinates of the full graphics screen so that the user can point to any object on 
the screen. This means that XMInClainp and YMinClamp will be 0, and YMaxClamp 
will be 200, The value of XMaxClamp depends on the graphics mode in use; it will 
be 320 for 320-by-200 mode, or 640 for 640-by-200 mode To ensure that you can 
alwavs see the mouses arrow cursor, however, you may want to set XMaxClamp 
and YMaxClamp to values that are two or three pixels smaller than the full screen 
dimensions, 

UserlD is the ID code returned by MMStartup. It is used when the Event 
Manager calls the Memory Manager to allocate any blocks it needs to operate. 

To shut down the Event Manager, call EM Shutdown, It requires no parameters. 
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Table 5—1; Events Handled In the Invent Manager 



Maim Events 


Keyboard Events 


Mouse-down 

Mouse -up 


Key-down 

A n to -key 


Window Events 


Special Events 


Update 
Activate 


Desk accessory 
Switch 

Device driver 
Application-defined (4) 



EVENT TYPES 

The Event Manager supports 16 types of events. Tl s includes a null event that is 
reported when no other type of event lias taken place efbre a request for an event 
is made with GetNextEvent Two of the 16 event ty _-s are not currently in use, SO 
there are really only 11 event types that may be reported, 

The different events handled by the Event Manager can be broken into four 
groups: mouse events, keyboard events, window events, and special events. See 
the breakdown in table 5-1. 

Mouse Events 

There are two mouse events, mouse-down and mouse-up. A mouse-down event 
occurs when a released mouse button is pressed. A mouse-up event occurs when a 
pressed mouse button is released. 

The Event Manager actually works with a two-button mouse (or an alternative 
pointing device with two buttons), but the same event codes for mouseup and 
mouse-down are reported for either button. You can determine which button was 
actually involved in the event by examining the Modifiers field of the event record 
returned by GetNextEvent, as you will see later in this chapter. 

You can determine the state of the mouse button directly with the Button 
function: 

PHA -.space for result 

PushWord #0 ^button number (0 or 1) 

_Bu t ton 
PLA -.True = button is down 

Fur the standard CS mouse, the button number must always be zero. The Boolean 
result is true (non-zero) if the button is down or false (zero) if it is not. 
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Keyboard Events 

The two keyboard events arc key-down and auto-key. A key-down event occurs 
when a released character key is pressed. A character key is one which generates 
an ASCII character code when pressed by itself. Every key on the keyboard is a 
character key except tin- Shift, Caps Lock, Open- Apple (Command), Control, and 
Option (Solid-Apple) keys. These keys are called modifier keys because they are 
usually pressed at the same time as a character key to change, or modify, the ASCII 
code it would otherwise generate. 

If you hold down a character key long enough it will begin to repeat itself. The 
act of repetition is called an auto-key event. The repeat rate can be set with the 
Control Panel desk accessory; you can even turn off the auto-repeat feature if you 
wish. 

Window Events 

The two window-related events are update and activate. An update event occurs 
when a portion of a window on the screen becomes exposed to view. This happens 
when the window is first created, when an overlapping window is moved aside, or 
when the window is enlarged. 

An activate event occurs when a window becomes active or inactive. By conven- 
tion, an active window is one that is to be affected by subsequent commands and 
drawing operations. The active window is highlighted in a distinctive way on the 
screen. 

To determine the reason for an activate event, you can examine a bit flag in the 
Modifiers flag of the event record returned by GetNextEvent. If the bit is 0, the 
activate event actually corresponds to a window becoming inactive. 



Special Events 

Most of the events not already discussed above are rarely used by an application. 
There are four application-defined events an application can post in the queue to 
report a custom event, perhaps the occurrence of a specific combination of events. 

The desk accessory event occurs when a user enters Control-Open Apple-Esc 
from the keyboard. It is never reported to the application by GetNextEvent; rather, 
it is trapped by the operating system's main event-handling routine and handled by 
popping up the Classic Desk Accessory menu (the one containing the Control Panel 
entry). 

A switch event occurs when the user clicks a switcher control icon to transfer 
control to another application in memory. A switcher program is not yet available 
for the gs, however. 

A driver for an I/O device can report a device driver event when it has received 
data. It may also report an event If it is ready to send data. 
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Figure 5—1. The Even I Mask Used by GetNextEvent and Taskmaster 



applicetion *4 

application *3 
application *2 
application *1 
device driver ~ 

desk accessory 
switch 



15141 1211|10 9 8 | 7 6 5 4 3 21 



activate/deactivate 



Ni n i'.: An event type is selected if its bit is I. otherwise it is ignored. 



null event 

mou3e tfowr 
mouse up 
key down 
[reserved] 
auto- key 
update 
[reserved] 



GETNEXTEVENT AND THE EVENT LOOP 

The Event Manager function that scans the event queue for the presence of an 
event is GetNextEvent. GetNextEvent returns a Boolean (true/false) result indicat- 
ing whether there was anything in the queue. If the queue is empty, the result is 
false (zero), and the application can complete the event loop by calling GetNextEvent 
again, 

Here is how to call GetNextEvent: 



PHA 

PushHord #$FFFF 

PushPtr EventRec 

_Get NextEvent 

PLA 



ispace for result 

; event mask 

^Pointer to event record 

■>Pop Boolean result 



The event mask tells GetNextEvent which events are to be reported. As shown in 
figure 5-1, each bit in the event mask word corresponds to a particular type of 
event. If the bit corresponding to an event is 1, that event can be reported. If you 
are interested in all types of events, pass an event mask of $FFFF to GetNextEvent. 
EventRec is a 16-byte event record. GetNextEvent fills the event record with 
information describing the event it removes from the queue. The structure of an 
event record is as follows: 
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EventRec 


A NOP 




*ha t 


DS 


2 


message 


DS 


A 


when 


DS 


A 


where 


DS 


A 


modifiers 


d i : 


? 



•,event code (integer) 

;event message (long word) 

V ticks since system startup {long word) 

5 mouse position (point) 

;modifier flags (integer) 

It is also advisable to reserve space for two other long word fields immediately 
following the event record: TaskData and TaskMask. They are used by the Task- 
Master function (described below), not by GetNextEvent You will probably use 
TaskMaster more often. 

The What Field 

The What field of the record contains the event code, an integer from to 15 
identifying what type of event occurred: 



= null event (no event occurred) 

1 = mousedown event 

2 — mouse-up event 

3 = key-down event 

4 = [not used] 

5 = auto-key event (a key was repeated) 

6 = window update even! 

7 = I not used] 

8 = window activate event 

9 = switch event 

10= desk accessory event 
11= device driver even! 
1 2 = application-defined event 
1 3 = application-defined event 
14 — application-defined event 
1 S = application-defined event 

Notice thai two codes in this range, 4 and 7, are not presently defined. On the 
Macintosh, an event code of 4 corresponds to a key-up event. 

The Message Field 

The Message field of the event record holds a 4-byte event message containing more 
information about the event. The content of the event message depends on the 
event type: 
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mouse-down button number (0 or 1) 

mouse-up button number (0 or 1) 

key-down ASCII character code (0 to 127) 

auto-key ASCII character code (0 to 127) 

window update Pointer to window 

window activate Painter to window 

device driver Defined by the device driver 

application -defined Defined by the application 

The event message for all other event types is undefined. 

The When Field 

File When field contains the time when the event took place. It is expressed in 
ticks since system start-up. A tick is a unit of time equal to one-sixtieth of a second. 

The Where Field 

The Where Held holds the vertical and horizontal position of the mouse on the 
screen when the event occurred. The position is calculated using the global coor- 
dinate system. In this coordinate system, the origin is the top left-hand corner of 
the screen and the horizontal and vertical axes increase to the right and down, 
respectively. 



The Modifiers Field 

The last field in an event record holds the modifier flags (see figure 5-2). These 
flags indicate the states of the keyboard modifier keys, the keypad, and the mouse 
buttons when the event took place. 

Modifier keys are keys that, by themselves, do not generate character codes when 
you press them: Shift. Caps Lock, Control, Option (also called Solid-Apple), and 
Open-Apple (also called Command). An application will inspect the modifier flags 
if it is designed to differentiate between events that take place when a modifier key 
is pressed and events that arc unmodified. For example, an application might want 
to let a user select a single icon by clicking a mouse button over that icon, or it 
might allow the user to select a group of icons by clicking the mouse button over 
each icon while holding down either Shift key. When such an application receives 
a mouse-down event from GetNcxtEvent, it would check the modifiers field to see 
if the Shift key was being pressed. 

The flag for a modifier key is 1 if the key is down, and if it is up. The BtnOState 
and Btnl State flags behave in the opposite way — a 1 corresponds to a button-up 
state . 
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Figure 5-2. The Format of the Modifiers Field of an Event Record 
or Task Record 



~r 1 r - 

not used 



1 t 



10 



not used 



1 = mouse down 
= mouse up 



1 = command key down 

■ command key up 

1 = shift keg down 

= shift key up 

1 = caps lock down 

■ caps lock up 

1 - option key down 
= option key up 



B 



imand Key ■ Open-Apple Option Key = Solid Apple 



1 = activate 
= deactivate 

1 = system/appl 
switch 

= no c ha nge i n 
window type 



Two other flags in the Modifiers field relate only to window activate/deactivate 
events. One flag, ActiveFlag, indicates whether the- window is being activated (1) 
or deactivated (0), and the other flag indicates whether the newly activated window 
is of a different type from the previously active window (1) or whether it is the same 
type (0), [Windows are either application windows or system windows. System 
windows are those created by New Desk Accessories; see chapter 9, ) 

The Event Loop 

The code for a simple event loop is remarkably straightforward: 



EvtLoop PHA 

PushWord #*FFFF 



; Space for result 
;Event mask: all events 

PushPtr EventRec ;Pointer to event record 

_GetNextEvent 

PLA ;Get the Boolean result 

BEQ EvtLoop ; Branch if no event 

Until an event occurs, the code between EvtLoop and the 'BEQ EvtLoop" instruc- 
tion is executed again and again. This is because the result is always false (S0O0O), 
which means that the zero flag is set after the PLA instruction, When an event is 
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reported, the result is true (nan-zero), the zero flag is cleared by the PLA instruction, 
and control passes through the bottom of the loop. 

The code following the loop can read the event type code from the What field of 
the event record and then pass control to the subroutine that handles that event 
type. Here is an example ol a piece <»l code thai does just that; 



LDfi 


What 


ASL 


A 


TAX 




JMP 


(EvtTable, X) 


EvtTable DC 


I ' I gnore f 


DC 


I ' DoflouseDown 


ij:; 


I ' DoMouseUp ' 


DC 


I ' DoKeyDown ' 


DC 


I ' Ignore* 


DC 


I • DoMouseDown 


DC 


I 'DoUpdate' 


DC 


I ' I gnore • 


DC 


I 'DoAct iwate' 


DC 


I ' Ignore' 


DC 


I ' I gnore ' 


DC 


I ' DoDr iver ' 


DC 


I 'DoApplt • 


DC 


I 'DoAppia 1 


DC 


I 'DoAppl3 ' 


DC 


I 'DoAppH' 



Get event type code 
Double it to get table offset 
Set up index for JMP (addr T K) 
Jump to event handler 

Nu 1 1 event 

Mouse -down 

Mouse-up 

Key-down 

[not used] 

Auto-key 

Window update 

[not used] 

Window activate 

Switch 

Desk Accessory 

Device Driver 

Application-defined #1 

Application-defined #2 

Application-defined #3 

Application-defined #1 



Ignore JMP EvtLoop 

Notice how this technique works. The entries in EvtTable are the addresses of the 
handlers for each event type, in event- type order. Because each address is two bytes 
long, the entry for a particular event is at an offset from EvtTable equal to two times 
the event type code value. This means that you can jump to the handler with a 
JMP ( EvtTable, X) instruction, where X holds the offset. 

If the application deals with only a few types of events, it may be more convenient 
to use a scries of CMP (compare) instructions to route the application to the proper 
event handler. Suppose, for example, an application handles mouse-down and key- 
down events but ignores every other type of event. You could pass control to the 
two event handlers using a code fragment like this: 



LDA What 



;Get event type code 



CMP #1 

BNE CheclcKD 

BRL DoMouseDown 



;Is it mouse-down? 
; No, so branch 
; Yes, so branch 



134 Event Management 



CheckKD CMP #3 

BNE Ignore 

BRL DoKeyDown 

Ignore JMP EvtLoop 



; ta it key-down? 
5 No , 50 branch 
; Y e s i 5 o branch 

■, Back to the event loop 



Notice that BRL rather than BRA instructions are used to branch to the event- 
handling subroutines. This is because the target address of a BRL instruction can 
be anywhere in the 64K program bank, whereas the target address for a BRA 
instruction is restricted to an address in the range -128 to + 127 bytes from the next 
instruction. 

If GetNextEvent returns a non-null event, it automatically removes the event 
from the queue. To determine what the next ivi nt is without removing the event 
from the queue, use EventAvail: 



PHA 

PushWord #SFFFF 

PushWord EventRec 

_EventAvai 1 

PLA 



-.space for result 

; event mask 

^Pointer to event reeorc 

;Boolean: always true 



After calling EventAvail, information about tin- next event in the queue can be 
found in the event record. 

Before entering an event loop at the beginning of a program, you may want to 
remove any events which may be lingering in the event queue. To do this, call 
Flush Events: 



PHA 

PushWord #SFFFF 
PushWord #$0000 
_FlushEvent 5 

PLA 



(space for result 

jEventMask for events to remove 

■ t StopMask for events to keep 

; Mask for first event not removed 



The first mask passed to FlushEvents describes the types of events that are to be 
removed from the queue. The second mask, called StopMask, describes the types 
of events that are to stop the removal process. FlushEvents scans the queue trom 
the beginning and removes all events up to (but not including) any event described 
by StopMask. The result it returns is the mask for the first event which was not 
removed. If the result is zero, all events were removed. 

In most cases you will want to remove even event from the queue. To do this, 
use an EventMask of SFFFF and a StopMask of $0000, as in the example. 

POSTING EVENTS 

In certain situations it may he convenient to place events in the event queue 
yourself. For example, you would do this to pass application-defined events to the 
system. To place an event in the queue, call PostEvent; 
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PHA ;space for result 

PuahWord EventCode ;The euent code 

PushLong EventMsg ;The event message 

_PostF_vent 

PLA ;True = event was posted 

PostEvent plates the event described by EventCode and EventMsg in the event 
queue. It automatically assigns the current time, mouse location, and state of the 
modifier keys and mouse button to the other fields of the event record. There is an 
exception: for keyboard or mouse events, the modifiers word is set to the high- 
order word of EventMsg. 

HANDLING EVENTS 

An application may handle an event any way it wants to, of course. There are, 
however, certain rules that every application should Follow when handling events 
so as to conform to Apple's user-interface guidelines. This section explains what 
these rules are and how to react in special ways to mouse, keyboard, and window 
events. 

Before proceeding, a comment should be made about a useful function that is 
actually part of the Window Manager, not the Event Manager: TaskMaster, You use 
it much as you would use GetNextEvent; the difference is that TaskMaster processes 
certain events in accordance with the user- interface guidelines before returning 
control to (lie caller. This allows the programmer of an application to concentrate 
on writing code unique to the application. 

Here is an event loop using TaskMaster instead of GetNextEvent; 

Evtloop PHA -.space for result 

PushWord #1FFFF ;Event mask 

PushPtr TaskRec -.Pointer to task record 
_Ta sk Master 

PLA ;Pop the task code 

BEQ EvtLoop (Branch if nothing to do 

Looks familiar right? 

The program in listing 5-1 is a simple program shell that might assist you in 
developing more complex desktop applications. At its core is a simple TaskMaster 
event loop 

The task record referred to in this calling sequence is just a standard event record 
followed by long word TaskData and TaskMask fields. 

TaskData is a long word in which TaskMaster sometimes returns a result (usually 
the pointer to a window). TaskMask is a bit vector indicating just which tasks 
TaskMaster is to handle (see figure 5-3). If the bit for a particular task is 0, the 
event code for the task is returned just as if you had called GetNextEvent. It is 
then up to the application to deal with it in an appropriate way. In most cases, you 
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Figure 5-3. The Format of the Task Mask Used by Task Master 



low -order word: 

|^5lt4ll3)l2]ll|l0|9 



7 6 



S|2|l|0| 

L_ 



- handle keyboard equivalents 
(menu selection) 

= handle window updates 

= handle mouse-down events 
(with RndWindow) 

= handle menu selection 
(with HenuSelect) 

= handle opening of DA items 
(With OpenNDA) 

= handle clicks in DA windows 
(wlthSystemClicK) 

I s handle drag operations 
(with DregWindow) 

1 = eclivete window if mouse is 
down inside window 

■ 1 = handle close box activity 
(withTrackGoAway) 

- 1 - handle 200m box activity 
(with TrockZoom) 

- 1 = handle grow box activity 

(with GrowWindow, SizeWindow) 

-1 = handle scrolling 



I = handle special Edit menu items 
and special Close item 



NOTE: Bits 13 through 33 of the task mask must In /rm 
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will want Task Master to handle everything it is designed for, so set the mask to 
S00001FFF. 

The first thing Task Master does is call GetNextEvent to get an event with which 
it can work. If then deals with the event in a standard way and returns a task code; 
if the code is 0, there is nothing more lor the application to do and it can loop back 
and call TaskMaster again. 

Assuming the standard task musk is used, TaskMaster may return the following 
codes: 

i nKey (3) When a key is pressed which is not the keyboard equiv- 

alent of a menu item 

in Up date (6) When the window to he updated does not have an 

update drawing subroutine; see chapter 6. 

wlnMenuBar (17) When a menu item is selected which is not a desk 

accessory item or a special item (undo, cut, copy, paste, 
clear, close); see chapter 7. 

wlnContent l^ 1 When a mouse-down event occurs in the content re- 

gion of the active window 

w I nGo A way (22) When a mouse-down event occurs in a close box of a 

window and the button is released in the close box, 

wlmSpecial (25) When a special menu item is selected which is not 

accepted by a desk accessory 

wlnFrame (27) When a mouse-down event occurs in the frame of an 

active window (other than scroll controls) 

TaskMaster also passes through mouse-up, auto-key, device driver, and application- 
defined events with no pre-processing oi any kind. 

The sections that follow cover ways to handle standard Event Manager events. 
In general , the descriptions given simply describe how TaskMaster handles the 
events. There an; no special requirements for reacting to switch, device driver, and 
application-defined events. In addition, the desk accessory event is handled inter- 
nally by the Event Manager. 

Mouse-down 

When a mouse down event occurs, the user is usually selecting an object on the 
screen. The program must determine what the object is — it could be a menu bar, 
a window, a scroll control, or a line of text, for example — and then process the 
selection in an appropriate way before returning to the main event loop. Techniques 
for handling mouse-down events will be described in detail in chapters 6 and 7. 
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Mouse-up 

Mouse-up events are often handled by terminating an activity that began with the 
previous mouse-down event. The classic example of such an activity is the dragging 
of an object on the screen: while the mouse button is down, a selected object Follows 
the cursor around the screen; when the button is released, the object is released 
and fixed in place. The program in listing 5-2, for example, lets you size a rectangle 
by dragging the mouse and letting go. 

' Mouse-up events may also be handled by determining whether the button was 
released when the mouse cursor was still in the same position on the screen as 
when the mouse was first pressed, if it was not, the application may want to ignore 
the mouse click. For example, the user-interface guidelines insist that a program 
Ignore a mouse-down event in the close or zoom box of a window if the button is 
not also released in the box. The rationale for this dictum is that if the user leaves 
the vicinity of the box, he probably wants to cancel the operation. 

Another operation involving a mouse-up event is a double-click— the pressing 
and releasing of the mouse button twice in quick succession. A double-click is 
frequently used to shortcut an operation that normally requires two separate clicks, 
such as the launching of an application from a program selector utility Two consec- 
utive clicks are to be treated as a doubleclick, instead of as two unrelated clicks, it 
the following conditions are true: the time (in ticks) between the mouse-up event 
for the first click and the mouse-down event for the second must be less than the 
DblTime parameter; and both clicks must take place within the same object or 
within a few pixels of the object. 

To read the current setting of the DblT.me parameter, use the Event Managers 

Get DblTime function: 

PHA ;Space for result (long word) 

PHA 

_GetDblTime 

PLA ;Pop the result 

STA DblTime ; ( low) 

PLA 

STA DblTime +2 ■, (high) 

The default value for DblTime is 30 ticks, but it can be adjusted using the cs's 
Control Panel. The program in listing 5-3 shows how to detect double clicks; when 
it finds one. it draws a small black box on the screen 

In each of the above three scenarios, the mouse-up event IS closely related to 
the previous mousedown event. For this reason, mouse-up events are best handled 
during the processing of the mouse-down event Mousedown events that occur m 
the main event loop can be ignored. 
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In the handler For a mouse-down event, use the Event Manager's StillDown 
function to wait for a mouse-up event to occur so that you can stop dragging an 
object, check that the mouse is still in an action hox. check for a double-click, or 
whatever. Until the StillDown function returns a false {zero) result, the mouse 
button is still down. Here is the calling sequence for StillDown: 

PHA ; space for Boolean result 

Pushklord #0 ;button number (always tor mouse) 

_St i 1 IDown 

PLA ;Pop the result 

BNE ItsDown ;Branch if it is still down 

BEO ItsUp -.Branch if it is up 

StillDown docs not actually remove the mouse-up event from the event queue- — 
GetNextEvent takes care of that when you return to the event loop. If you prefer 
that the event he removed, use the WaitMouseUp function instead of StillDown; 
in all other respects the two functions work the same. You might want to use 
WaitMouseUp if your event loop does not ignore mouse-up events. 

Key-down and Auto-key 

An application should react to a key-down event by checking to see if it corresponds 
to the keyboard equivalent of a menu item (this is covered in chapter 7). If it is not 
there is no standard way of dealing with the character — it depends on the application. 
If the user is entering a line of text, for example, the program should display the 
character on the screen and update the active cursor position. 

Auto-key events are usually handled in the same way as key-down events. You 
may want to ignore them if they correspond to menu item equivalents, however, 
because you do not usually want commands entered from menus to repeat auto- 
matically. 

Window Update 

An update event occurs w f hen a portion of a window needs to be redrawn. Such an 
event occurs in the following situations; 

• When the window first appears on the screen (after NewWindow or 
ShowWindow) 

• When an overlapping window is moved aside to make visible a new portion 
of the windows content region 

• When the window is enlarged by tugging on its grow box 

• When a portion of the content region is made invalid with InvalRect or 

InvalRgn 
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The windows update region defines the portion of a window that requires redrawing. 
This may be the entire content region or any part of it. Details on how to handle 

update events will be given in chapter 6. 



Window Activate 

Window activate events actually include deactivate events. To distinguish between 
the two, examine bit of the Modifiers field of the event record If it is 1, it is an 
activate event. 

Activate events are handled by highlighting the window and bringing it to the 
front of the screen. Highlighting involves drawing racing stripes in the title portion 
of the window and drawing the detailed structure of scroll controls. These areas in 
an inactive window are white. 

Activate events are described in more detail in chapter 6, 



CURSORS 

The cOTSOr-handllOg functions are actually part of the QuickDraw tool set (see 
chapter 6) but it is appropriate to discuss them here because they arc tied to a 
rather common user activity (although not an event handled by the Event Manager): 
moving the mouse. A cursor is a small icon that moves around the screen as you 
move the mouse around the tabletop. It serves to inform the user of the position of 
the mouse on the screen. 

(A program can determine the current position of the mouse by calling GetMouse: 

PushPtr MousePosn ;Ptr to space for result 
_GetMou5e 
RTS 
MousePosn DS 4 -.Position in local coordinates 

Note that the mouse position is returned in the local coordinates of the currently 
active drawing window. See the next chapter for a discussion oi local coordinates,! 
The standard cursor is a small arrow. To make it visible, call InitCursor (no 
parameters) after starting up QuickDraw. You can switch to a custom cursor using 
the SetCursor function: 

PushPtr TheCursor jPointer to cursor record 

_SetCur aor 

TTie Cursor points to a cursor record that defines the size and shape of the cursor. 
The structure of this record is as follows: 
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Cursor heighl (word) Height of cursor rectangle in rows 

Cursor width (word) Width of cursor rectangle- in words 

Cursor image (b) I Cursor definition, row by row 

Cursor mask (hvles) Cursor mask, row by row 

Hot spot Y (word): The hot spot is the position in the rectangle that is 
I lot spot \ v. ord) aliped with the mouse position 

Note that the width of the cursor takes into account the " chunkincss' of the graphics 
screen that is, whether two (640-by-200 mode) or four (32O-by-20O mode) tut* are 
needed to define a dot on the screen. (Screen resolution is discussed in detail in the 
next chapter) Note also that the last word in the group of words defining a row m the 

cursor must be zero. , 

The cursor mask indicates which parts of the cursor image are to be drawn on the 
screen. Only those bits m the cursor image that correspond to 1 bits in the cursor mask 
are used. The cursor mask is generally a filled-in outline of the cursor surrounded by a 
one-pixel " R love." This makes the cursor visible even .f it is positioned over an area that 
is the same color as the cursor, m 

Below is the record for a cursor in 320 graphics mode (1 bits per pixel); this forms an 
I-beam, the standard text-insertion cursor 



DC 

DC 



12 i 1 1 ■ ^Height (in pixel rows) 

I2 , 4 i -.Width (in words) 



DC H'0000000000000000' 

DC H'OOOOFFFOFFFOOOOO' 

DC H'OOOOOOOFOOOOOOOO' 

DC H'OOQOOQOFOOQOQQOO' 

DC H'OOOOOOOFOOOOOOOO' 

DC H'OOOOOOOFOOOOOOOO' 

DC n'OOOOOOOFOOOOOOOQ' 

DC H'OOOOOOOFOOOOOOOO 1 

DC H'OOOOOOOFOOOOOOOO' 

DC H'OOOOFFFOFFFOOOOO' 

DC H'0000000000000000' 



DC H'OOOOFFFOFFFOOOOO' 

DC H'OOOFFFFFFFFFOOOO' 

DC H'OOOOFFFFFFFOOOOO' 

DC H' 0O0OOOFFFOOO000O • 

DC H'OOOOOOFFFOOOOOOO' 

DC H'OOOOOOFFFOOOOOOO" 

DC H'OOOOOOFFFOOOOOOO' 

DC H'OOOOOOFFFOOOOOOO' 

DC H'OOOOFFFFFFFOOOOO' 
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DC H'OOOFFFFFFFFFOODO' 
DC H'GOOOFFFOFFFOOQQQ 1 



DC 12 '9, 7' ;Hot spot (base of I -Beam) 

You tan locate the eursor record for the currently active cursor with GetCursorAdr: 



PHA ;Space for result 

PHA 

_Oe t Cursor Ad r 

PopLong CursorPtr 'iPop the result 

I! you wish to switch cursors temporarily, use GetCursorAdr to get the pointer to 
the current cursor and then use the pointer when restoring the cursor with Set- 
Cursor. 

If you want to remove the eursor From the screen for any reason, call HideCursor. 
To make it visible again, call ShowCursor. Neither function requires parameters or 
returns results. 

if you are using a cursor to identify a position where text may be entered, you 
may want to make the cursor blink by hiding and showing it at a fixed rate. The 
blink rate should be the one set by the Control Panels Cursor Flash command; it 
can be r< the GetCarelTime function: 



PHA rapace for result 

PHA 

_GetCaretTime 
PopLong CaretTime 

The long result is expressed in ticks (sixtieths of a second). The default Control 
Panel setting is 30 (half a second). 

One handy cursor function is ObscureCursor. It removes the cursor from the 
screen until the mouse moves. Use it to eliminate the mouse cursor while a user is 
typing something in from the keyboard. It requires no parameters 

The QuickDraw Auxiliary tool set contains a function called WaitCursor that you 
can use to change the eursor lo a wristwatch. You should call it just before performing 
a time-consuming operation to inform the user that the program will not be respond- 
ing to input for a while. To restore the arrow cursor, call InitCursor. WaitCursor 
requires no input parameters and returns BO results. 

To start up the QuickDraw Auxiliary tool set, call the QDAuxStartup function. 
To shut it down, call QDAuxShutDown. Neither function requires parameters nor 
returns results. 
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CLOCK FUNCTIONS 

As mentioned in chapter 1, the CIS has a built-in clock/calendar chip that maintains 
the current time and date. You can set the current time and date with the Control 
Panel. 

One common I/O operation (which, like mouse* movement, is not handled by the 
Event Manager) isi reading the time and date so that you can display it on the screen 
or insert it in a printed report. The Miscellaneous Tool Set includes two functions 
you can use to read the clock: ReadAsciiTime and ReadTimeHex. 

(The start up and shut down functions for the Miscellaneous Tool Set are MTStart- 
up and MTShutDown. Neither one requires parameters nor returns results.) 

ReadAsciiTime, as its name suggests, returns a 20-byte ASCII-encoded character 
string describing the current da*e and time. To call it, pass a pointer to a previously- 
aHoeated 20-byte data area; 

PushPtr TimeString ^Pointer to "airing area 

_J?eadAsc i i Time ;Read the time 

RTS 

TimeString DS 20 ;Space for time string 

The time string is not preceded by a length byte. It is always exactly 20 characters 
long and the high-order bit in each byte is set to one. 

The string returned by ReadAsciiTime uses one of three date formats and one of 
two time formats. Altogether, there are six formatting combinations (dd = day of 
month, MM = month, yy = year, hh = hours, mm = minutes, and SS = seconds): 

dd/MM/yy hh:mm:sa XM (XM = AM or PM) 

MM/dd/yy hh:mm:s5 XM (this is the default) 

yy/MM/dd hh:mm:55 XM 

dd/MM/yy hh;mm:ss (24-hour military format) 

MM/dd/yy hh:mm:55 

yy/MM/dd hhrmmias 

The date and time formats actually used are those set by the Clock command in the 
Control Panel. 

If you are not satisfied with the look of the string that ReadAsciiTime returns, 
use ReadTimeHex to return the current time and date in binary form and then 
manipulate the data as you like. Here is how to call ReadTimeHex: 

PHA ;Space "for DayOf Week / [ u nuaed ] bytes 

PHA ;Space for Month/DayQf Month 

PHA ;Space for Year/Hour 

PHA ;Space for Minute/Second 
_ReadTimeHex 
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SEP 


#*20 


LDNGA 


OFF 


PLA 




STA 


Second 


PLA 




STA 


Mi nut e 


PLA 




STA 


Hour 


PLA 




STA 


Year 


PLA 




STA 


DayQfManth 


PLA 




STA 


Month 


PLA 




PLA 




STA 


DayQfWeek 


REP 


#120 


LDNGA 


ON 



;5witch to 8-bit A for byte data 

;Pop Second 

;Pop Minute 

;Pop Hour 

;Pop Year 

-,Pop Day of Month 

;Pop Month 

;Pop unused byte 
;Pop Day of Week 

,Return to 1G-bit accumulator 



The values returned by ReadTimeHex are as follows: 



FUNCTION VALUE 

DayOfWeek 1.7 (1 = Sunday, 2= Monday, etc- ) 

Year 0..99 (Year minus 1900) 

Month 0. ,11 (1 = January, 2— February, etc. 

DayOfMonth 0. .30 (Day of month minus 1) 

Hours 0.23 

Minutes 0.59 

Seconds 0, . 59 



Remember that ReadTimeHex was the function used by the user-defined TimeTonls 
tool set in chapter 3 to determine the day of the week code prior to converting it to a 
text string. 

One other useful time-related function is TickCount Use it to determine the number 
of ticks that have elapsed since the t;s was started up (a tick is l/60th of a second) . 
Here is how to call TickCount: 



PHA 

PHA 

_TickCount 

PopLong NumTicks 



;5pace for long result 



-,Pop the result 



Clock Functions 145 



To put a delay loop in a program, call TickCount once before entering the loop and 
then keep calling it until the difference between the result and the starting value is 
greater than or equal to the desired delay. 

To generate a two-second (120-tick) delay, for example, use the following code 
fragment: 



;Get starting tick count 



PHA 




PHA 




_Tlc 


kCount 


PopL 


ong TickStart 


DelayLoop PHA 




PHA 




.Tie 


kCount 


PopL 


ong TickCurr 


S£C 




LDA 


TickCurr 


SBC 


TickStart 


STA 


TickCurr 


LDA 


TictCurr+2 


SBC 


TickStart+2 


STA 


TickCurr+2 


SEC 




LDA 


TickCurr 


SBC 


#120 


LDA 


TlckCurr+2 


SBC 


#0 



;Get current tick count 



;Calculate time difference 



-.Subtract 120 (long) 



BCC DelayLoop jBranch if < 120 



RTS 



TickStart DS 4 
TickCurr DS 4 



Notice that the carry Bag, which is set before a subtraction operation, becomes clear 
if the number being subtracted is greater than or equal to the number in the 
accumulator. 
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REFERENCE SECTION 

Table R5-1: The Major Functions in the Event Manager Tool Set ($06) 



Function Name 



Function Stack 
Sitmher Parameters 



Button 


$0D 


result (W) 
Button Num (WJ 


EM Startup 


$02 


DPAddr 
QueueSize (W) 
XMinCkmp i\V) 
XMaxCIamp (W) 
VMiiiClamp (Wi 
YMaxClamp (W) 
UserlD(W) 


EMShutDown 


$03 


[no parameters] 


Even LAv ail 


$0B 


result (W) 
EventMask (W) 
EvenlRecord (L) 


FlushEvents 


$15 


result (W) 
Event Mask (W: 
StopMask (W) 


GetCaretTime 


S12 


result (L) 


GetDblTime 


an 


result (L) 


Get Mouse 


soc 


Mouse LocPtr (L) 


GetNextEvent 


$0A 


result (W) 
EventMask (W 
Event Record (L) 



Description of 
Parameter 



Boolean: is the button down? 
Button number 
Address of 1 page in bank 
Size of" event queue 
Mouse minimum (horizontal! 
Mouse maximum (horizontal) 
Mouse minimum (vertical) 
Mouse maximum (vertical) 
ID ta# for memory allocation 

Boolean; always true 

Event mask 

Ptr to event record 

Mask for next event in queue 

Mask for events to be flushed 

Masks for events to be kept 

Ticks between cursor blinks 

Interval for double-clicks 

Ptr to mouse point (local) 

Boolean: was event retrieved? 

Event mask 

Ptr to space for event record 
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Function Name 


Function 
Number 


Stack 
Parameters 


Description of 
Parameter 


Post Event 


$14 


result (W) 


Boolean: was event posted? 






EventCode (W) 


Event code to plaee in queue 






EventMsg (L) 


Message word for event 
record 


Still Down 


$0E 


result i\\ : 


Boolean: button still down? 






Button Num £W) 


Button number 


TickCount 


$10 


result il 


Ticks since system startup 


WaitMouseUp 


SOF 


result (W) 


Boolean: button still down? 






Button Num (W) 


Button number 



Table R5-2: Event Manager Error Codes 



Error 
Code 



Description of Error Condition 



$0601 
$0602 
$0603 
$0604 
$0605 
$0606 



$0681 

$0682 



The Event Manager has already been started up. 

Reset error. 

The Event Manager is not active, 

The event code is greater than 15. 

The specified button number is not or 1. 

The size of the event queue is greater than 3639. 

There is not enough memory for the event 
queue. 

The event queue is seriously damaged. 

The handle to the event queue is damaged. 
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Tabic R5-3: Useful Functions in the Window Manager Tool Set ($0E) 



Function Name 


Ftt nction 
Number 


Stack Description of 
Parameters Parameter 


TaskMaster 


$ID 


result ;\Y ' Event code 
Event Mask (W) Event mask 
TaskRecord (L) Ptr to space for task record 


Table R5-4: Useful Functions 


m the QuickDraw II Tool Set ($04) 


Function Name 


Function 
Number 


Stack Description of 
Parameters Parameter 


GetCursorAdr 


$8F 


result (L) ptr to cursor record 


HideCursor 


$90 


[no parameters] 


InitCursor 


$CA 


[no parameters] 


ObscureCursor 


$92 


[no parameters] 


SetCursor 


S8E 


CursorRecord (L) ptr to cursor record 


ShowCursor 


$91 


[no parameters] 


Table R5-5: Useful Functions 


in the QuickDraw Auxiliary Tool Set ($12) 


Function Name 


Function Stack Description of 
Number Parameters Parameter 


QDAuxShutDown 


$03 


[no parameters] 


QDAuxStartup 


$02 


[no parameters! 


Waif Cursor 


$0A 


Ino parameters] 


Table R5=6: Useful Functions 


in the Miscellaneous Tool Set ($03) 


Function Same 


Function 
Number 


Stack Description of 
Parameters Parameter 


MTSbutDown 


$03 


[no parameters] 


MTStartup 


S<!2 


[no parameters] 
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Function 


Stack 


Description of 


Function Name 


Number 


Parameters 


Parameter 


ReadAsciiTime 


$0F 


TimeString (L) 


Ptr to 20-byte time string 


ReadTimeHex 


SOD 


result (W) 


1 )ay of week (high byte) 






result (W) 


Month (high), Date (low) 






result <W) 


Year- 1900 (high). Hour (low) 






result (W) 


Minute (high), Second (low) 
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Listing 5-1: A Program for Assisting in the Development of Other Programs 



* You can use this program aa a shell * 

* for writing a complete GS application. » 

LIST OFF 

ABSADDR DN 
INSTItlE ON 
GEN OFF 
SYMBOL OFF 

KEEP SHELL ;0bject code file 

MCOPY SHELL, MAC ;Haero file 

MyCcde START 

Using GlobalData 
Using StartData 

JSR DoStartUp ;Start up all tool sets 
j Define and display the menu bar: 

PuahLong *0 
PushPtr MenuL2 
_NewMenu 
PushWord *0 
.Inaer tMenu 

PushLong #0 
PushPtr MenuLI 
_NewMenu 
PushWord #0 
_] nser tMenu 

PuahWord #1 

_FixflppleMenu ;Add desk accessories to menu 

PHA 

_FixMenuBar ;Adjust size of menus/menu bar 

PLA 

_DrawMenuBar 

•, Define and display the window: 

PHA ; Space for result 

PHA 

PushPtr MainWjndow -.Pointer to window record 
NewWindow 
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PopLong WindowPtr 
Ini tCursor 



;Save pointer to window record 
;Turn an the arrow cursor 



EvtLoop PHA 



PushWor 


d 'SFFFF 


PushPtr 


EuentRec 


_Tas kMas ter 


PLA 




CMP 


#wl nMenuBar 


BEQ 


"Jo Me - u 



\ A L iow all event s 



*,Get result coder 
?Menu item selected' 
;Yes, so branch 



•, [check for other events herel 
BRL EvtLoop 



;Back for more 



i Handle menu Item selections. (The items must be 
•■> numbered sequentially from 256.) 



DoMenu 



LDA 

SEC 
SBC 
ASL 
TAX 
JSR 



TasfcDa ta 

#256 
A 

(MenuTable , X 



PushWord #0 
PushWord TaskData+2 
Hi 1 1 teMenu 



; Get menu item ID 

{Convert to base 

; x 2 to step into table 



; Highl ight ing off 
:&et menu ID 



BRA EvtLoop 
; Table of menu item subroutine addresses: 



MenuTable 


DC 


1 'DoAbout I ' 




DC 


I ' DoQu i 1 1 ' 


i 


DC 


I ' DoYour I tern 1 


DoAbout I 


RTS 




DoQuit I 


PLA 






JMP 


DoShutDown 




END 






CDPY 


STANDARD. ASM 



Item 256 
Item 257 
Item 258 . . . and so on 



;Pop return address 

■, Shut down all tool sets 
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GlobaiData DATA 

; Menu/item line lists. If you add more items, number them 
; consecutively from 258. 






MenuLI DC C >>6\N1X* ,H" 0D r ;Apple menu 

DC C^About this program . . . \N256W ,H' OD' 

Menul_2 DC C>> File \N2',H'GD' ;File menu 

DC C'##Qiiit\N257»Qq' .H'QD" 

DC C ' . ' ; End of menu 



; Window parameters: 

WindowPtr DS 4 



; Pointer to window 



MyTitie STR 



GS Application 






Mai nWindow 


DC 


12 


' Wi ndEnd-Ma l nW 


indow ' 








DC 


1 ■ 


%1 00000001 0100101 ' 




window frame definition 




DC 


14 


■MyTi 


Lie 1 






Pointer to window title 




dc 


14 


iQ' 








ref con 




DC 


[ ' 


0,0,0 


Qi 






zoom rectangle 




DC 


14 


iOi 








color table 




DC 


I ' 


0,0' 








origin offset 




DC 


I ■ 


0,0' 








height, width data area 




DC 


r • 


t 0' 








height, width max window 




DC 


i • 


0,0' 








vert , hor iz scroll 




DC 


i • 


0,0' 








vert , hor i z page 




DC 


14 


"0' 








info bar refcon 




DC 


14 


<0' 








frame defproc 




DC 


[4 


IQ» 








info bar defproc 




DC 


12 


■Qt 








info bar height 




DC 


M 


l l 








content defproc 


WindRect 


DC 


i ' 


30,10 


,185,400' 






Contrnt region rectangle 




DC 


M 


. -1 1 








At the front 




DC 


14 


'0' 








Storage 


WindEnd 


ANOP 












EventRec 


ANDP 












Uhat 


DS 


2 






; Event 


code 


Message 


DS 


i 






; Event 


resu 1 1 


When 


DS 


4 






-.Ticks 


5 i nee star tup 


Where 


DS 


A 






; Mouse 


locat ion ( q loba 1 ) 


Modif ler s 


DS 


2 






;5tatus of modifier keys 


Task Data 


DS 


A 






jTaskflaster data 


Task Mask 


DC 


14 


1 tOOOOIFFF* 









END 
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Listing 5—2; A Program Showing How to Use StillDown and GetMouse 



* This program shows how to use the 

* StillDown and GetMouse functions. By 

* pulling on the mouse with the button 

* down, you can create a rectangle of 

* any size. 

LIST OFF 

ABSADDR ON 

INSTIME ON 

GEN OFF 

SYMBOL OFF 



KEEP 


DRAG 


MCOPV 


DRAG. MAC 


START 




Using 


GlobalData 


JSR 


DoSlar tUp 



;0bject code file 
; Macro file 



My C o d e 



; Define and display the window: 



EvtLoop 



PuahLong #0 ;Space for result 

PushPtr MainWindow ;Pointer to window record 

_NewWi ndow 

_Stor tDrawmg ^Prepare to draw in window 



; A 1 1 event s 



_ I ni 


tc 


ur sor 


PHA 






PushWord #*FFFF 


PushPt 


p EventRec 


_Tas 


k n 


aster 


PL A 






CMP 




'IceyDownEvt 


BEQ 




Exit 


CMP 




#wl nContent 


BNE 




EvtLoop 


JSR 




DoBoxes 


BRA 




EvtLoop 


JMP 




DoShu IDown 


END 







•,Get result code 

*, Key -down? 

■, Yes , so branch 

?in content region** 
; no, so ignore 



Exit 
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; Display a box on the screen. Size it using 
t dragging techniques. 

DoBoxes START 

Using GlobalData 

PushPtr Where 

_Globa IToLocai ^convert to window coords 

1 Initial rectangle is a single pixel: 

LDA Where+h 

STA BoxRect+left 

5TA BoxRec t+r ight 

LDA Where+v 

5TA BoxRect+top 

STA BoxRec t *bot t am 

Stretchlt PusbPtr BoxRect 

_lnvertRect ;draw the new rectangle 

Stretchltl PHA ;space for result 

PushWord #0 ;mouse button 

_St i 1 1 Down 
PLA 
BEQ DragExit sbranch if not still down 

PushPtr MouaeLoc ;Get current mouse position 

_GetMouse ; (local coords) 

; If current location is same as last one, do nothing. This 
; avoids excessive flashing an the screen. 



-.Horizontal matches? 
*, N o , so branch 

-.Vertical matches 9 
•.Yes, so branch 

;Save the new position 





LDA 




CloiiseLoc * h 




CMP 




LastLoc+h 




BNE 




SaveLoe 




LDA 




Clous eLoc * v 




CMP 




Las t Loc*v 




BEQ 




Stretchltl 


SaveLoe 


LDA 




MouseLoc+h 




STA 




LastLoc+h 




LDA 




MouseLoc + u 




STA 




LastLoc+v 




PushPt 


r 


BoxRect 




1 river 


tRect 



;erase the old rectanqle 



; Arrange coordinates of the new rectangle in the 
; standard top, left, bottom, right (TLBR) order: 
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LDA 


MouseLoc+h ; 






CMP 


Where *h "> 






BCC 


_1 






STA 


BoxRect *r lght 






LDA 


Where+h 






STA 


BoxRect+lef t 






BRA 


_2 


_1 




STA 


BoxRect * left 






LDA 


Nhere-»h 






STA 


BoxRect *r lght 


_2 




LDA 


MouseLoc+v 






CMP 


Where + v ', 






BCC 


_3 I 






STA 


BoxReet+bottom 






LDA 


Where + v 






STA 


QoxRec I * top 






BRL 


StretchI t 


_3 




STA 


BoxRect+top 






LDA 


Where+v 






STA 


BoxRec t *bot torn 






BRL 


StretchI t 


DragE 


xit 


RTS 
END 








COPY 


STANDARD. ASM 


Globa 


IData DATA 





la new horizontal position 
to the left of the base point? 

Yes, 50 branch 



Is new vertical position 
; above the base point? 
;Ye5, so branch 



; Window parameters: 

MyTitle STR ' Drag Demo ' 



MainWindow DC 


12'WindEnd-MainWindow 


DC 


1 '%1 0000000001 00000 ' 


DC 


14 'MyTitle 1 


dc 


14*0' 


DC 


I '0» 0,0,0' 


DC 


1 4 ' ■ 


DC 


!'C,0' 


DC 


1 '0,0' 


DC 


P0 ,0' 


DC 


I '0,0' 


DC 


1'0,0' 


DC 


I 4 ■ » 



j t i t le bar on ly 

jPointer to window title 

; ref con 

; zoom rectangle 

;color table 

•.initial origin offset 

; he ight ,widt h data area 

; height .width max window 

• vert , hori z 1 ine 

■, ver t i hor i z page 

s info bar ref con 
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DC 


!2'0' 




DC 


L4 ' Q ' 




DC 


14 '0 » 




DC 


I4»0' 


WindRect 


DC 


I '30,1 , 185 T SO0 ' 




DC 


I4'-1 i 




DC 


I4< ' 


Wi ndE nd 


ANOP 




MouseLoc 


DS 


i 


BoxRect 


DS 


a 


LastLoc 


DS 


4 


EventRec 


ANOP 




What 


DS 


2 


Message 


DS 


-1 


When 


DS 


4 


Where 


DS 


4 


Mod i f i era 


DS 


2 


TaskData 


DS 


4 


TaskMask 


DC 


I4'$00001FFF' 



; inf o bar height 

; frame defproc 

; info bar def proe 

-.content defproc 

•.Content region rectangle 

;At the front 

-.Storage 



; a point 

\ Coordinates of stretched rectangle 

■, a point 



Event code 

Event result 

Ticks since startup 

Mouse location (global) 

Status of modifier Iteya 

TaskMaster data 



END 



Listing 5-3: A Program Showing How to Use GetDblTime and WaitMousel'p 



• This program shows how to detect a double-click 


• 


• operation. When you double-click, it displays a 


* 


■ black rectangle on the screen. 


* 



LIST 


OFF 




SYMBOL 


OFF 




ABSADDR 


ON 




INSTIME 


m 




GEN 


ON 




KEEP 


DOUBLE 


-.Object code file 


MCOPY 


DOUBLE. MAC 


jMacro file 



MyCode 



START 

Using GlobaiData 
Using StartData 



JSR 



DoStartUp 



; Define and display the windows 
ShowWind PHA 

PHA 

PushPtr MainWlndow 
NewUindow 



'.Space for result 
^Pointer to window record 
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PopL 


ong 


Wi ndowPtr 




_Ini 


t C u r 5 o r 


tLoop 


PHA 








PushWor 


d **FFFF 




PuahPtr 


TaskRec 




_Tas 


kfla 


5 ter 




PLA 








CMP 




• k eyDownE vt 




BEQ 




Exit 




CMP 




*wl nContent 




BNE 




EvtLoop 




JSR 




DoClick 




BRA 




EvtLoop 


it 


JMP 
END 




DoShu tDown 


Check 


for a d 


ouble-c lick. 



;Save pointer to window record 



;A11 events 



;Get result code 

; Key -down? 

\ Yea , ao branch 

•, in content region? 
■,no, so ignore 



If It's a double c 1 i c k , display a rectangle 
filled with the pen pattern, 

DoClick START 

Using GlobalData 

PushLong WindowPtr 

_Star tDrawing ;Prepare to draw in window 

PHA ;Space for result 

PHA 

_GetDblTime ;get double-click time 

PopLong DblTime 

PushPtr Where {Convert mouse-down location 

_G1 oba IToLoca 1 ; to window coordinates 

1 Calculate time since last mouse-up: 



SEC 




LDA 


When 


SBC 


Up Time 


STA 


TheGap 


LDA 


When+£ 


SBC 


UpTime»2 


STA 


TheGap*2 
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% Check the mouse-up / mouse-down interval J 



SEC 




LDA 


DblTime 


SBC 


TheGap 


LDA 


DblTime*2 


SBC 


TheGap+2 


BCS 


Doubled 



*, branch if DblTime > m TheGap 

; Wait until mouse button is released, then save time: 

WaitFarUp PHA ;space for result 

PushWord *0 ;mouse button (*0) 

_WaitMouseUp ;Wait for the following mouse-up event 

PLft ;Get Boolean result 

BNE WaitForUp ;Loop until mouse is up 

pHA ;apace for result 

PHfl 

TickCount jGet current tick count 

PopLong UpTime '.Get the result 
RTS 

j Me had a double-click, so draw a solid rectangle: 
Doubled ANOP 



CLC 




LDA 


Where+h 


STA 


OurBox+lef t 


ADC 


#30 


STA 


QurBox+r ight 


CLC 




LDA 


Uhere+v 


STA 


DurBox+top 


ADC 


#10 


STA 


OurBox+bot torn 



PushPtr OurBe-x 
PaintRect ;Draw the solid box 



RTS 



DblTime 


DS 


4 


UpTime 


DC 


I 4 • 


TheGap 


DS 


4 


QurBox 


DS 


8 



END 



;LDNG (double-click time) 
•lime of last mouse-up 
■, up-down time gap 
; Rectangle 
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COPY 



GlobalDeta DATA 



STANDARD. ASM 



; Window parameters: 
UindowPtr DS 4 
MyTitle STR 



-.Pointer to window record 



Double-Click Demo 



MainWlndow DC 


12 i WindEnd- MainWlndow 


DC 


I'X1 101110110100101 ' 


DC 


M'MyTit le' 


DC 


14 » » 


DC 


I '0,0,0,0' 


DC 


M«0« 


DC 


1'0,0' 


DC 


I ' , ' 


DC 


1'0,0' 


DC 


J « , ■ 


DC 


I » Q , < 


DC 


r 4 • o * 


DC 


! g • • 


DC 


I 4 » ' 


DC 


1 4 • ' 


DC 


1 4 • ' 


DC 


I '31 ,6,182,608' 


DC 


I4«-1 f 


DC 


t4'fl' 


WindEnd ANOP 





Size of table 

window frame type 

Pointer to window title 

ref con 

zoom rectangle 

color table (0 * default) 

document offset 

height, width of data area 

height ,width max window 

vert, horiz line movement 

vert, horiz page movement 

info bar refcon 

info bar height 

frame defproc (0 = standard! 

info bar defproc 

content defproc 

Content region rectangle 

At the front 

Storage {use MM) 



is k Master task recorc 



TaskRec 


ANDP 




What 


DS 


2 


Me ssage 


DS 


A 


When 


D5 


4 


Where 


DS 


4 


Modifiers 


DS 


2 


Tas k Data 


DS 


4 


Tas kMas k 


DC 


I 



M'f QQQ01FFF' 



;Event code 

;Event result 

;Ticks since startup 

; Mouse location (global) 

;Status of modifier keys 

jTaskMaster data 

; TasfcMas ter handles all 



END 
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CHAPTER 6 



Windows and 
Graphics 



This chapter, and the three that follow, examine ways to develop applications that 
use the cs's super high-resolution graphics screen as a Macintosh -like desktop. The 
discussion will begin with an analysis oi" windows and then will move on to pull- 
down menus, dialog and alert boxes, and finally desk accessories. The G5 has tool 
sets for dealing with all these standard desktop features, 

A window is an object on the desktop that acts as the private display screen for 
a single document. The underlying document ma) be a series of lines of text or any 
arbitrary graphic image, and it maj be any size. If the underlying document is 
larger than the portion of the window in which drawing operations appear (called 
the content region), however, not all of it can be seen at once. To permit the viewing 
of any portion of a large document, you can add bottom and right scroll controls to 
a window. By adjusting these controls, it is possible to move any portion of the 
document into the content region, 

The us handles windows in a flexible way. You can define as many windows as 
memory permits and you can display them all on the screen at once. A window is 
totally independent of any other window, so it can appear anywhere on the screen, 
even though it may overlap or totally obscure another window. Some windows are 
resizable and some may be dragged around the screen with the mouse. 

By convention, the frontmost window is the active window, the one that will be 
affected by drawing operations; other windows are said to be inactive. The active 
window is drawn in a distinctive way, with a solid block in the title bar and 
highlighted scroll controls. This distinguishes it from inactive windows, which show 
only the outlines of the scroll controls and title bar. 

This chapter covers how the Window Manager (tool set 14) can be used to create 
various types of windows and to display them on the screen. Changing the size and 
appearance of windows, moving windows around the screen, handling window's that 
have scroll controls, and dealing with multiple windows are also discussed. 
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Of course, windows are tint m i \ useful unless you can display something; in them. 
At the end of the chapter, many of the text and graphics drawing functions in the 
QuickDraw II tool set will he examinee] QuickDraw II is responsible for handling 
all tasks that involve drawing something mi the super high-resolution graphics 
screen. The Window Manager, for example, uses QuickDraw II to draw window 
frames and special window icons. 

THE SUPER HIGH-RESOLUTION GRAPHICS SCREEN 

Before discussing the Window Manager, it is necessary to take I close look at the 
characteristics of the super high-resolution graphics video display mode. Once you 
understand how it works, you will be better able to use many of the Window 
Manager and QuickDraw II functions, (-specially the ones that permit you to ma- 
nipulate colors. 

As shown in figure 6-1, the video display buffer for the super high-resolution 
graphics mode is 1 from $2000 to S9CFF in bank $E1 of memory. The area 

from $9D(X) to $9DFF holds 200 scanline control bytes and the area from S9E00 to 
$9FFF holds 16 color palettes. The area from 12000 to $9FFF in bank $01 shadows 
to the same area in bank SE1 if shadowing is enabled. (QuickDraw II does not 
enable shadowing; it accesses bank SE1 video locations directly.) 

Two bits in the New-Video register at $E0C029 control the characteristics of the 
super high-resolution screen {see figure 6-2). 

To turn on the super high-resolution display mode, set hit 7 of the New-Video 
register to 1. Bit 6 must also be set so there will be a linear relationship between 
the display buffer and the position of a pixel on the screen. You want the linear 
relationship because screen drawing calculations can be done more quickly. 
QuickDraw II sets both bits for you when you call the QDStartup function. 

When you leave super high-resolution mode, store a $01 in the New-Video 
register, This ensures that linearization is off, as normal lie-style applications expect 
this, (It also permits main/auxiliary memory switching just like on a He.) QuickDraw- 
does this when you call QDShulDown. 

Pixel dimensions of the graphics screen arc either 320 wide by 200 high or 640 
by 200. Each line is defined by a group of 160 consecutive bytes in the video display 
buffer. With the linear memory map enabled, this means that the bytes defining a 
line begin at an offset (from $2000) that is 160 times the line number. The line 
numbers range from to 199. 

Each pixel in a line is associated with either four bits (320 mode) or two bits (640 
mode) in the display buffer. These bits define the color of the pixel. The assignment 
of pixels to bits lor a byte in the display buffer is shown in figure 6-3. 

When this scheme is used, a pixel can be one of sixteen colors in 320 mode or 
one of four, colors in 640 mode. As will be shown below, the color definitions are 
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Figure 6-1. The Super High-resolution Graphics Display Butler 



$A000 

I9E00 

$9D00 



$2000 



Color Palettes 
(sixteen 32-byte tables) 

Scanline Control Bytes 
(first 200 bytes) 



Video RAM 
( 160 bytes/scan line; 
200 scan lines) 



Bank $E1 



note; Locations $2000 881 Ff In bawls $01 shadow to this bank [f shadowing is enabled. 



stored in a palette, or color table, that defines sixteen colors- In 640 mode, only 
four of these colors are available to a given pixel, the lour that are available depend 
on what column the pixel is ill, as indicated in the figure. 

The pixel width and color palette for a given horizontal line are controlled by its 
SCanline control hutr i.SCBL The SCBs for the screen are stored, in line order, in B 
200-byte table beginning at $9D00 in bank SE1. The format of an SCB is shown in 
figure 6—1. 

When the fill mode bit of an SCB is on, color number in the palette becomes 
inactive. When a pixel is assigned a color number of 0, the pixel takes on the same 
color as the previous non-zero pixel in the line. 
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Figure 6—2. The* New-video Register 



7 


6 


5 


4 


3 


2 


1 






IE0C029 



(must be 1; enables 
bank latch) 



1 = inhibit color in double high-res 
= full color in double high-res 



_ 1 = linear video map from $2000-$9FFF (bank 
= standard video map from S2000-S9FFF 

m 1 = turn on super high-resolution screen display 
= turn off super high-resolution screen display 



$E1) 



The interrupt bit in the SCR is normally off, You may want to enable interrupts so 
that yon tan update tin* video buffer during video retrace operations; this eliminates 
Dickering in animation sequences, You could also change the color palettes during 
an interrupt to effectively increase the number of different colors visible on the 
screen, 

A palette, or color table, is a group of sixteen words, each describing a particular 
color, as follows; 



7 



Izerol 



Red 



high-order byte 



7 


3 


Green 


Blue 



low-order byte 



\s you can sec. the red, green, and blue components of the color word are each 4 
bits long- This means you can choose from 4,09fi different colors. 

Table fi-1 shows the standard color tables QuickDraw II uses for each of the 
sixteen lfi-color palettes when it starts up in the 64Q-by-20G and the 320-by-200 

mode. 
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Figure 6—3, Super High-resolution Color 



320 mode: 
7 



left pixel 

J 1 L 



3 

1 1 1 



right pixel 

J I l_ 



color number (0 to 15) 
color number (o to 15) 



640 mode: 



7 


5 


3 


1 


i 


1 

i 


i 


1 











right pixel 

(selects from colors 4 to 7 
in the palette) 

- middle-right pixel 
(selects from colors to 3 
in the palette) 



• middle-left pixel 
(selects from colors 12 to 15 
in the palette) 

- left pixel 
(selects from colors 8 to 11 
in the palette) 
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Figure 6—4. The Format of a Seanline Control Byte 



7 


6 


5 


4 


3 


2 


1 






—(must be 0) 



color palette number 
(0 to 15) 



1 = fill mode is active 
= fill mode is inactive 



1 = generate interrupt on horizontal retrace 
= no interrupts 



= 



line is 640 pixels wide 
line is 320 pixels wide 



You can return a copy of this table by pushing a pointer to a sixteen-word area and 
calling the QuickDraw InitColorTable function. 

In 640 mode, QuickDraw expects color numbers from to 3 only. In this situation, 
a color number is really an index into the group of four colors permitted for the 
pixel column in question. Notice that the lour groups of four colors in 640 mode 
are different — two of the groups use red and green as the second and third colors 
and two use blue and yellow. This means that when a horizontal line in color $02 
is drawn, alternate green and yellow pixels are drawn on the screen; they are so 
close together, however, that the line appears to be one solid color (lime green). An 
alternate red/green line looks purple. The creation of a new color by placing different 
colors close to one another is called dithering. By changing the 640-mode palette 
and taking advantage of the dithering phenomenon, ynu can create many other 
colors. 

Any euli' in any palette table can be changed at any time using QuickDraw's 
Set( "olorEn trv function: 



PushWord #0 
PushWord #8 
PushWord NewColor 
_SetCo lorEn t ry 



;Palette number (0 to 15) 
;Color number (0 to 15) 
;The new color value 
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Table 6-1: The Standard Color Tables; Used by QuickDraw 



Color 




320-by-200 Made 


640-hy-2(M Mode 


Number 


Value 


Color 


Value 


Color 


it 


$0000 


black 


$0000 


black 


1 


$0777 


dark gray 


$0F00 


red 


2 


$USII 


brown 


$00F0 


green 


3 


$072C 


purple 


SOFFF 


white 


•l 


$0Q0F 


blue- 


$0000 


black 


5 


$0080 


dark green 


$<XX)F 


blue 


6 


$0F70 


orange 


$0FF0 


yellow 


7 


$0D00 


red 


$0FFF 


white 


S 


$0FA9 


flesh 


$0000 


black 


9 


$0FF0 


yellow 


IOF00 


red 


10 


SOOEO 


green 


$OOF0 


green 


11 


S04DF 


light blue 


$0FFF 


white 


12 


$0DAF 


lilac 


$0000 


black 


13 


$078 F 


periwinkle blue 


$000F 


blue 


14 


$ocx:c: 


light gray 


$0FF0 


yellow 


15 


$0FFF 


white 


SOFFF 


white 



If you prefer, you can redefine the entire table al once by passing a palette number 
and a pointer to the palette definition to SetColorTable, 

There ire also QuickDraw functions for changing the standard scauline control 
bytes; SetSCB and SetAllSCBs. Use SetSCB to change the SCB for any particular 
line, or SetAllSCBs to assign the same SCB to all lines at once, 

Here is how to use SetSCB: 



PuahWord #188 
PushWord #S8a 
.SetSCB 



;Line number 
•New SCB 



In this example, line #18S becomes 640 pixels wide and is associated with palette 

Because the SetAllSCBs Function affects all lines, it requires only one parameter, 
the new SCB value. 
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Figure 6-5, The Structure of a Window 




niinrronii'ni 



_InsertMenu 

PushlJord «1 
JixRppleHenu 

PHD 

JixNenuBar 

PLfl 

JrawNenuBar 

InitCursor 



« P — -ft 



;fldd Dfis to Apple menu 

;fidjust size of menus/menu 

;Display menu bar 
;Turn on the arrow cursor 



Define and display the window: 




INTRODUCING THE WINDOW 

As shown in figure 6-5, a standard window is made up of a rectangular content 
region in which the window's underlying document is drawn. Surrounding the 
content region is a window frame in which any window controls defined for the 
window appear. Methods for assigning window controls to a window are covered 
later in this chapter. The window in figure n 43 is fully-loaded"; its frame contains 
every type of control supported by the Window Manager. In practice, most windows 
use only a subset of these controls. 

Just above the content region of this window is the information Ixir. Most 
windows do not have an information bar; if one is defined, it usually contains a 
subtitle lor the window. The main title appears in a title bar above the information 
bar. The title bar also serves as the mechanism for dragging a window around the 
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screen, To drug a window, move the mouse cursor into the title bar, press the 
mouse button and then move the mouse while holding the button down; to "drop" 
the window into place, release the mou.se button. 

Two small rectangles, the close box and zoom box. appear at the left and right 
sides, of the title bar respectively. (You must include a title bar il you want a close 
box or a zoom box.) Although these boxes are inside the rectangle describing the 
title bar, they are not actually part ol the titlr bar itself. The close box is what a 
user clicks to remove a window from the screen. The zoom box lets a user quickly 
resize a window: when it is clicked for the first time, the window expands to cover 
the entire screen (oi whatever size is specified by the programmer); when it is 
clicked again, ii returns i<> its previous size. 

A user can also resize a window by dragging in the grow box region of a window. 
When it is dragged, an outline of the resized window (with the top-left corner fixed 
in place) follows the mouse until the button is released 

The scroU bars permit a user to view an) portion of a window's underlying 
document When you click the mouse in a scroll arrow or a page region, or when 
you drag a tliumh, whatever Is in the window scrolls and a new portion oi the 
document becomes visible. Consider how the right (vertical) scroll bar works, for 
example. When you click the up or down arrow, the document scrolls up or down 
li\ a fixed number of pixel lines corresponding to one line ol whatever is in the 
document. For a text document, this number is usually set to the line spacing. 
Clicks in the page regions usually scroll the document In the entire height of the 
content region, or tin- entire height less one line. Finally, you can quickly bring 
an) portion ol the document into view by dragging the scroll bars thumb up or 
down in the scroll bars elevator shaft. Bottom (horizon tal'i scroll bars behave in 
similar ways, except that they control horizontal movement within the document. 

The size ot the thumb reflects how much oi the document is being shown in the 
content region. Again, consider a right scroll bar. The ratio of the height of the 
thumb to the height ol the scroll bai is the same lis the ratio ol the height ol the 
content region to the height of the document. 11 the entire height oi the document 
fits in the content region, the thumb occupies the entire scroll bar. 

The position of the thumb within the scroll bar tells you what portion of the 
document is in the content region The closer the thumb is to the top of a right 
scroll bar (or to the left of a bottom scroll bar), for example, the closer you are to 
the top edge (or left edge) of the document. In effect, the ratio of the size of a page 
region in a scroll bar to the size of the bar is the same as the ratio of the size of the 
relevant off-screen portion of a window (the portion above the top, bottom, left, or 
right, as the case may be) to the size ot the entire window. 

The window behavior just described does not happen automatically. It is up to 
the programmer to write the application in such a way that standard actions occur 
when window activity is detected. 
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Figure 6-6. The Format of the PortSCB Byte 



6 



5 4 



2 







PortSCB 



color palette number 
always (0 to 15) 

1 - 640x200 mode 
= 320x200 mode 



lill WINDOW RECORD 

When you first define a window (with the NewWindow function;, a window record 
is created that the Window Manager uses to keep track of window parameters. One 
important field in a window record is a QuickDraw data structure called a GrafPort. 
A GrafPort completely describes a drawing environment: the position of the drawing 
area, the attributes of the drawing pen, the character font to be used for drawing 
text, the typeface and color, the background pattern, and SO on. 

The first part of a GrafPort is called the Portlnfo -field. It describes the position 
and size of a rectangular area in memory within which an active drawing area is 
defined. In most cases, this area will be inside the super high-resolution video buffer 
so that you can see the effect of drawing operations. 

Portlnio is a data structure of type Loclnfn and is made up of the following five 
fields; 

• PortSCB (byte] 

• [Reserved] (byte) 

• PointerToPixellmage (long) 

• Width (word) 

• BoundsRect (rectangle! 

PortSCB defines the color palette associated with the GrafPort and the bit size of 
the pixels in the drawing area. Its meaning is explained in figure CMi 

Although sou can associate one of sixteen color palettes with each line in the 
drawing area (which is usually the super high-resolution display buffer), QuickDraw 
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initially assigns the same palette (palette #01 to each line. (The structure of a palette 
was described earlier in this chapter. ) 

PointerToPixellmage contains the address of die top left-hand corner of a rectan- 
gular desktop in which the active drawing area of the GrafPort is located. For the 
super high-resolution screen, this is location $E 120000. Width is the numher of 
bytes required to define a line of pixels extending from the left edge of the drawing 
area to the right edge; it is L60 for the super high-resolution screen. 

The precise width of the drawing area is defined by the boundary rectangle, 
BoundsRecl. Like any QuickDraw rectangle, this one is defined by four integers 
representing the positions of the top, left, bottom, and right sides of the rectangle. 

Another important field in a window record is PortRect, which is also a rectangle. 
PortRect describes the portion of BoundsRect to which GrafPort drawing operations 
will be confined. If part of PortRect lies outside BoundsRect, drawing will be 
restricted to the portion inside BoundsRect. For a window, this is the content 

region. 

To determine the current value of PortRect, use Get PortRect 

PushPtr WindRect ;Pointer to rectangle 

_GetPortRect -.Read the value of PortRect 

RTS 

WindRect DS 8 i* rectangle is « words (8 bytes) 

PortRect also defines a heat coordinate system lor the GrafPort, a system used by 
all drawing functions affecting the GrafPort In this system, the origin ol the 
GrafPort— its top left-hand comer— has the coordinates given by the first two words 
of the PortRect. These coordinates are anchored to this corner and do not change 
even if PortRect is moved from place to place within the area oi memory described 
by the boundary rectangle (i.e., the desktop). 

If you do want to change the coordinates of the origin, perhaps to the convenient 
(0,0) standard or to the scroll position within the document, use the SetOrigin 
function: 

PushWord NewX ; new horizontal coordinate 

PuahWord NewY ;new vertical coordinate 

_SetQr igin 

SetOrigin assigns the specified values to the top left comer of PortRect. The bottom 
right coordinate of PortRect is adjusted accordingly to maintain the size of PortRect. 
BoundsRect is also adjusted by SetOrigin to keep it at the same relative position to 

PortRect. 

The other standard coordinate system, the global coordinate system, assigns the 
top left-hand corner of the total drawing area given by BoundsRect (usually the 
super high-resolution screen) to the (0,0) coordinate. This is the coordinate system 
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used by a point in the Where Held of an event record, for example. Use the 
ClobalTo Local function to convert a global coordinate to a local coordinate: 

PushPtr ThePoint ^Pointer to global coordinate 

_01oba lToLocal 

To convert in the opposite direction, from local to global, use LocalToGlobal: 

PushPtr ThePoint jPointer to local coordinate 

_Loca 1 ToGlO'ba 1 

LocalToGlobal when you have to compare points expressed in the local coor- 
dinates of different GrafPorts. Converting all the points to the same coordinate 
system will enable you to make meaningful comparisons. 

The conceptual drawing space for QuickDraw operations is a square grid that 15 
32K pixels wide and 32K pixels high. The coordinate origin is in the center, so the 
coordinate limits for the horizontal and vertical axes range from -16K to +16K. Tf 
you try to draw outside this range, the system will behave unpredictably. 

Keep in mind that even when you draw inside the absolute boundaries only the 
bits for pixels falling within the content region of the window (and not obscured by 
other windows) will be transferred to the memory area associated with the content 
region. 

WINDOW MANAGER START-UP AND SHUT-DOWN OPERATIONS 

Because the Window Manager functions use QuickDraw 11 functions to perform 
screen -drawing operations, you must initialize QuickDraw before initializing the 
Window Manager. To do this, use the Following calling sequence; 

PushWord DPAddr ;Address of 3-page area in bank 100 

PushWord #S80 »S8Q - 640x200 / *O0 = 320x200 

PushWord #0 ^MaxWidth (0 = screen width) 

PushWord UaerlD ;ID returned by MMStartup 
_QDStartup 

DPAddr is the two-byte address of a three-page area in bank $00 that QuickDraw 
uses for direct page space. This space can be allocated with the Memory Manager. 
The second parameter pushed. MaslerSCB, is the scanline control byte QuickDraw 
will use for each of the 200 lines on the screen. It is normally $80 for 640-by-200 
mode or $00 for 320-by-200 mode. The next word pushed is MaxWidth, the width 
i in bytes) of the largest pixel area in which QuickDraw will be asked to draw; a 
value of sets MaxWidth to the screen width (160 bytes). The last parameter is the 
program ID that was returned by MMStartup. 

To initialize the Window Manager itself use WmdStartup: 
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PushWord UserlD ;1D returned by MMStartup 

_Wind5tar tup 

WindStartup's only parameter, UserlD, is the ID number returned by MMStartup. 
WindStartup clears the Window Managers internal list of windows and defines 
the entire super high-resolution screen us the Window Manager's desktop. It does 
not draw the desktop itself, tor that use Refresh Desktop: 

PushLong #0 ;0 - entire screen 

_Ref reshDesk top 

Refresh Desktop uses a default background pattern and color to draw the desktop. 
When you are all through with the Window Manager at the end of a program, 
call the WindShutDown function to release the data structures and memory areas 
it uses WindShutDown requires no parameters, 

CREATING A WINDOW 

To create a new window, use NewWindow. It builds a window record data structure 
from a specified parameter list and adds the record to .in internal list of window 
record, maintained by the Window Manager. It may or may not display the window 
on the screen, depending on how you initially define the WFrame parameter (see 
below). If you define it as invisible, you can display it by passing the window pointer 
to the ShowWindow function. 

NewWindow requires only one parameter, a pointer to a parameter list describing 
the properties of the window. It returns a pointer to the window n r ii 

for the window record could not be allocated). Here is how to use New- 
Window: 

r-t ;Space for result [long) 

PHA 

PuahPtr WindParms -.Pointer to parameter list 

_NewWindow 

PopLong WindowPtr ;Save window pointer 

N ewVV i ndow Para mete r s 

The parameter list referred to in the call to NewWindow contains nineteen param- 
eters thai describe the appearance of the window. Some parameters are only tor the 
use of the TaskMaster Function, which retrieves events and handles mouse-down 
activity in a window, The subroutine in listing 6-1 shows how to define the window 
shown in figure fv-5. 

A description of each of the parameters, in order of appearance in the parameter 

list, follows: 
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Figure 6-7. The Window Frame Bit Vector (wFrame) Used by New-Window 
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F_Title 

F_Close 

F_A1ert 

F_Rscrl 

F_BScrl 

F_Grow 

F_Flex 

F_Zoom 



_f 



l_ 



F_HilUed 

F_Zoomed 

F_Alloceted 

F_Ctrl_Tie 

F_1nfo 

F_Vis 
F_QContent 

■F_Move 



paramlength (word). Hits is the number of bytes in the window parameter table. 

wFrame (word). This is a bit vector describing the appearance of the window 
frame (see figure 6-7). It lets you create windows with or without the following 
window controls in the frame: 

• Title bar 

• Close box 

• Zoom box 

• Right scroll bar 

• Bottom scroll bar 

• Grow box 

• information bar 

You can also use it to indicate whether tin- window is movable (can be dragged 
around the screenl at its zoomed size, or visible. Additional bits reflect whether 
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the window was created by NewWindow. whether the controls are tied to the 
window, and whether a mouse click that activates a window is to he returned to the 
application. 

With two exceptions, each control is independent of any other- The first exception 
is the grow box — if its bit is set, the right scroll bar or bottom scroll bar bit must 
also he set, The second exception relates to the title bar — if the close box or zoom 
box bits are set. the title bar bit must be set as well. Although it is not required, it 
you define a window with a zoom box, you should also define a grow box so that 
the window can be made any convenient size, 

A common window frame value is %1101 1 1 1 111 100101 ($DFE5). This defines a 
visible window that has a title bar, close box, scroll bats, grow box. and a zoom box. 
The window is also draggable. 

Here is the meaning of each bit in the window frame bit vector: 



bit 
FH1LITED 



bit I 
F.ZOOMED 



bit 2 

F ALLOCATED 



bit 3 

F CTRL TIE 



bit 4 
F INFO 



bit 5 

F VIS 



1 — Window is highlighted (active) 

= Window is uuhighlighted (inactive) 

This bit is used by the Window Manager alter the window is 
defined: its value is ignored by NewWindow. 

1 = Window is zoomed out 

= Window is zoomed in 

If the window is zoomed out, it will zoom in when the zoom 
box is clicked next. If it is zoomed in, it will zoom out. 

1 = Window record was allocated by NewWindow 

= Window record was allocated by the application 

If this bit is set (the usual case), the window record is auto- 
matically disposed of when CloseWindow is called. 

1 = Controls in the window are not tied to the activr'inaetive 

state of the window 

= Controls are tied to the state of the window 

Tin usual value for this bit is 0. This causes the scroll controls 
to be dimmed when the window is deactivated. 

1 = The window has an information bar 

= The window does not have an information bar 

If this hit is set, the wlnfoDefProc field of the window record 
must point to an information bar drawing procedure, The field 
must not be zero. 

1 — The window is visible 

— The window is invisible 

If this bit i.s 0, the window will not appear on the screen afte] 

NewWindow is called. Use Show Window to make the window 

visible. 
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bite 
F.QCONTENT 



bit 7 

I _ MOVE 



bit 8 
F_ZOOM 



bit 9 
F_FLEX 



bit 10 
F.GROW 



bit 11 
F.BSCRL 

bit 12 
F.RSCRL 

bit 13 

F ALERT 



bit 14 
F.CLOSE 



1 = TaskM aster handles a mouse-down event in an inactive 
window by activating the window and retaining the event 
for the application 

= TaskMaster returns a null event to the application after 

handling a mouse-down event to activate a window 
If this bit is set to 1, the user does not have to click the mouse 
twice to select something in an inactive window, 

1 = The window can be dragged by its title bar 

= The window cannot be dragged 

If a window has a title bar, this bit should be set to 1 so that 
the user is free to position it on the screen wherever he likes. 

1 = The window has a zoom box 

= The window does not have a zoom box 

If this bit is set, bit 15 (F.TITLE) must also be set so that the 
window will have a title bar. 

1 = The origin of the window does not change when the 

wind* >u is zoom oi resized 

= The origin of the window moves up and to the right as 

the window grows beyond the limits of its underlying 
data 
For most applications, this bit should be set to 1. 

1 ■ The window has a grow box 

= The window does not have a grow box 

A window with a grow box should also have a right or a bottom 
scroll bar. A zoom box is also recommended but not necessary. 

1 — The window has a bottom scroll bar 

= The window does not have a bottom scroll bar 

1 — The window has a right scroll bar 

= The window does not have a right scroll bar 

1 - The window uses an alert box window frame 

= "Hie window uses a standard window frame 

You will usually clear this bit to for windows defined with 
NewWindow. Alert boxes are created using the Dialog Man- 
ager, If the hit is 1, F.GROW, F.CLOSE, FJNFO, F_ 
TITLE. F.BSCRE, and F.RSCRL must all be 0. 

1 = The window has a close box 

= The window does not have a close box 

If this bit is set, bit 15 (F_T1TLE) must also be set so that the 

window will have a title bar. 
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bit 15 1 = The window has a title har 

F TITLE = The window does not have a title bar 



wTitk (long). This is a pointer to the title of the window. The litle Is a string of 
ASCII-encoded characters preceded by a length byte, To isolate the title from the 
background pattern of the title bar include a space character at the beginning and 
end of the title string. 

uRefCon (long). This is a reference constant defined by the application. It is not 
used by any Window Manager functions. It can hold anything you like, such as a 
pointer or handle to a data area you would like to associate with the window. 

wZoom (rectangle). This rectangle describes the size of the content region when 
the window is zoomed by clicking in its zoom box. Like those ol any rectangle, this 
rectangles coordinates are in top, left, bottom, tight iTLBR) order. If you specify a 
zoom rectangle of (0,0,0,0), a default rectangle that describes the entire screen 
(except the menu bar) is used. 

tvColor (long). This is a pointer to the window frame's color table. If this pointer 
is zero, a default color table is used. 

wOrigin (point). This is the position in the window's underlying document that 
corresponds to the top left-hand corner of the content region. This value is used to 
compute the positions of the thumbs in the right and bottom scroll bars. TaskMaster 
updates this value in the window record when a scrolling operation occurs 
TaskMaster also uses SetOrigin to move the origin of the content region to this 
point before calling the routine to update the window (see below), the origin is reset 
to (0,0) on return from the update routine. If you draw inside a window outside of 
the update subroutine, first call StartDrawing to adjust the origin properly; use 
SetOrigin to return the origin to (0,0) after drawing. 

wData (long). This is the height {low word) and width (high word) of the entire 
document, measured in pixels. This data is needed to draw the right and bottom 
scroll bars properly. Set the height or width to if you are not using right or bottom 
scroll controls, respectively. 

uMta (long). This is the maximum allowable height (low word) and width (high 
word) of the content region when resizing the window. TaskMaster passes this value 
to GrowWindow when a mouse-down event occurs in the window's grow bos Set 
it to if you want to use the default value, which is the height and width of the 
desktop, 
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wScroll (long). This is the number of pixels to scroll the content region when the 
up or down arrow in the right scroll bar is selected (low word) and the number of 
pixels lo scroll when the left cur right arrow in the bottom scroll bar is selected (high 
word). These values are used by TaskMaster to handle activity in a scroll bar. 



wPage (long) I in, is the number of pixels to scroll the content region when the 
up or clown page region in the right scroll bar is selected (low word) and the number 
of pixels to scroll when the left or right page region in the bottom scroll bar is 
selected (high word! 1 . These values are used by TaskMaster to handle activity in a 
scroll bar. 



wlnfoRefCun (long). This is the reference constant passed to the information bar 
draw routine. This constant can be anything the application likes. It often holds a 
pointer to a line ol text to he drawn in the information bat 



wlnfoHeight (word). This is the height of the information bar, 



wFrameDefProc (long). This is a pointer to the window's definition procedure. 
Set this to for a standard document window. 



wlnfoDefProc (long). Ibis is the address of the routine TaskMaster calls to draw 
the contents of the information bar, Such a routine must be installed if the w Frame 
byte indicates that the window lias an information bar; if this routine is not installed, 
the system will crash when the window is drawn. The Window Manager pushes 
three parameters on the stack before calling the information bar subroutine with a 
JSL instruction; a pointer lo the enclosing rectangle for the information ban the 
wlnfoRefCon value, and a pointer lo the window. These parameters must be re- 
moved from the stack before the subroutine ends with an RTL instruction. Note 
that before the routine tries to access the application's direct page or dala space, it 
should set the direct page and data bank registers accordingly (after saving the ones 
passed to the routine). On exit, the initial values lor these registers must be restored. 



uContDe/Proc (long). This is the address of the routine TaskMaster calls to draw 
die window's content region in response to an update event. Before TaskMaster 
calls the routine, it sets the local coordinates of the top left corner of the content 
region to the positions indicated by the values of the scroll controls (if applicable] 
and calls Begin Update. On entry, the direct page and data bank registers may not 
be ihc same as when TaskMaster was called, so the routine will have to change 
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them to access the application's direct page and data areas. The routine must end 
with an RTL instruction, [f wContDefProc is <>. or if TaskMaster is not used, the 
application itself must trap update events and handle them in an appropriate way. 

u- Position (rectangle). This rectangle, given in global coordinates, describes the 
initial position and size of the window's content region. 

uFhme (long). This is a pointer hi the window behind which this window is to 
appear (long). IT the pointer is -I, the window appears on top; ifO, the window 
Appears at the bottom. 

trStorage (long). This is the address oi the memory area to use for the window 
record (long). Sel U to (I if NewWindow is to allocate the- memory space for yon by 
calling NewHandle (the usual case), 

THE INFORMATION BAR PROCEDURE 

The general structure of an information bar procedure is shown in listing 6-2. In 
this particular example, a line of text is centered and drawn in the Information bar. 
A pointer to the text string is in the w InioBcfCon parameter. 

UPDATING A WINDOW 

The wContDefProc (update) subroutine referred to in the NewWindow parameter 
list is important because it is responsible for ensuring that newly exposed portions 
of a window are properly filled in, Without such a subroutine, portions ol the 
window will he erased when other windows are moved From in front of it or when 
the window is enlarged The TextBeader program shown later in this chapter is an 
example of how to write such a subroutine for a window containing lines oi text. 

Ef wContDefProc is 0. update events are passed through to the application for 
handling. (You should clear wContl h-\V\ •< when designing New Desk Accessories 
because you cannot be sure that TaskMaster is being used bj the main application; 
see chapter 9.) The update handler is similar to a wContDefProc subroutine but 
must Include some extra window management chores. To handle updates, first call 
BeginUpdate: 

PushLong WindowPtr {Pointer to window 

_Beg i rilipda t e 

BeginUpdate saves the windows current visible region I which describes the portion 
of the windows content region you can actually see on the screen), sets the new 
visible region to the intersection of the old visible region and the update region, 
and then empties the update region. 
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After calling BeglnUpdate, pass the window pointer to StartDrawiug to select 
the window for drawing activity and tn align the origin of the content region to the 
position reflected by the values of the thumbs in the scroll controls. This aligns the 
active portion of the document with the window's content region. Then redraw the 
portion of the window's document that appears within the new visible region. To 
do this, it is actually easier to redraw the entire content region of the window, 
because doing so avoids the problem of determining how to draw just an arbitrary 
portion of it. To do this, of course, you must always keep a record of exactly what 
is in the window. This can be the most difficult part of developing an application. 

After the screen has been redrawn, call End Update to restore the original visible 
region: 

PushLong WindcwPtr ^Pointer to window 

_EndUpda t e 

Next, set the origin of the window back to (0,0) with SetOrigin: 

PuahWord #0 
PushWord #0 
_SetDr igi n 

The Window Manager does not work properly if you do not return the origin to 
(0,0) after updating the window. 

CHANCING THE PROPERTIES OF A WINDOW 

After vou have created a window with New Window, you will need to change some, 
ul that window's properties in certain situations. For instance, you should alter the 
DataSize parameter to reflect a change in the size of the window's underlying 
document so that the scroll controls can be redrawn in proper proportion, To change 
.such properties, you must update fields in the window' record created from die 
\. YvWindovv s parameter list, not in the parameter list itself. You do this with a 
group of Set functions, one for each of the named fields in the parameter list. 

Table 6-2 contains a list of the relevant Set functions. When you change a 
parameter, the appearance of a window may not immediately change to reflect the 
value of the new parameter. To force the window to be redrawn, first hide the 
window and then make it visible again: 

PushLong WindowPtr 

_HideHindow jRempve window from screen 

PushLong WindowPtr 

_ShQwWi,ndow j Ma k e the window visible 
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Table 6-2: Functions for Setting Window Parameters 



Function 



Description 



SetWFrame 

SetWTitlc 

SetWRefCon 

SetFuUBed 

SetFrameCoIor 

SetContentOrigin 

SetDataSize 
SetMaxGrow 

Set Scroll 

SetPage 

SetlnfoReFCon 

SetDefProc 

SetlnfoDraw 

SetContentDraw 



Sets the window frame bit vector 

Sets the title for the window 

Sets the reference constant for the window 

Sets the zoom rectangle for the window 

Sets the color table to be used with the window 

Sets the horizontal and vertical offsets to the 
data area corresponding to the top left-hand 
corner of the window 

Sets the width and height of the data area for a 
window^ 

Sets the maximum width and height for a 
window that can be resized 

Set* the number of pixels to scroll one line 
horizontally and the number of pixels to scroll 
one line vertically 

Sets the number of pixels to scroll one page 
horizontally and the number of pixels to scroll 
one page vertically 

Sets the parameter passed to the information 
bar drawing procedure 

Sets the address of the window definition 
procedure. 

Sets the address of the information bar drawing 
procedure 

Sets the address of the window's update 
procedure 



If there is more than one window on the screen, call SelectWindow after the code 
sequence above to make this window the active one. 

There are also Get functions corresponding to each Set function. Use them to 
determine the current values of the window parameters With some exceptions, 
Get functions are all called in the same general way 
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1. Push space for result (word or long) 

2. Push a pointer to the window record (long) 

3. Call the Cet function 

4. Pop the result (the window parameter) 

For a function dealing with strings, the result is a pointer to the string. 

The exceptions relate to those functions dealing with rectangles, strings, and 
other data structures longer than four bytes. Instead of pushing space for a result, 
push a pointer to a space for the rectangle or string. The function returns the result 
in this space, so you do not have to pop a result from the stack. 

REMOVING A WINDOW FROM THE DESKTOP 

When you are finished with a window for good, use CloseWindow to free up the 
space reserved for it (if it was created with New Window), remove it from the window 
list, and erase it from the screen: 

PushLong WindowPtr jPointer to window 

_C loseWindow 

Close Window causes the window in the plane just below the window that was closed 
(if any) to be highlighted. It also generates an activate event for this window. Once 
a window is closed, you cannot use it again unless you redefine it with NewWindow, 
If you simply want to erase a window from the screen without destroying its 
record, use Hide Window to make it invisible: 

PushLong WindowPtr '.Pointer to window 

_H ideWi ndow 

To make the window visible again, pass its pointer to the Show-Window function. 
You will also use Show Window to display a window for the first time if the visible 
bit in the window frame word is (J when you call NewWindow, 

Be aware that calling Show Window will not make the window active if there are 
other windows already on the screen. Use Select Window for that: 

PushLong WindowPtr jPointer to window 

_5e lectWindow -.activate the window 

SeleetWindow removes the highlighting from the previously active window, brings 
the specified window to the front of the screen and highlights it. and then generates 
the appropriate activate events. 

You will use SeleetWindow more often to activate an inactive, but visible, window 
when GetNextEvent returns a mouse-down event that FindWindow says took place 
inside an inactive window. If you are using a TaskMaster — rather than a Get- 
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NextEvent — event loop, you will not actually have to call SelectWindow, because 

Task Master calls it for you. 

To determine it the window in which an event took place is the active (frontmost) 
window, use FronlWindow: 

PHA " f 5pace far result 

PHfl 

_Fr on t Wi ndow 

PopLong CurrentWindaw ;Pop Ihe window pointer 

If the result. Current Window, matches the value of the window pointer that 
FindWindow returns, the activlt) did take plate in the active window, 

HANDLING MOUSE-DOWN ACTIVITY IN WINDOWS 

The user-interface guidelines define the actions that should take place when various 
parts of a window are clicked. For example, a click in an inactive window should 
activate the window and bring it to the front of the screen. The Window Managers 
TaskMaster function (introduced in chapter 5) perforins many of the standard actions 
for you, so use it unless you need to deal with a mouse-down event in a different 
rhis section describes exactly how TaskMaster reacts to various events so that 
if you want to handle them on your own, you will know roughly what to do. 

Here is a subroutine you could call to get a TaskMaster event to work with; the 
subroutine returns an event code in the accumulator: 

;Space for result 
; Al low all events 
; Pointer to task record 

sGet event code 
;Loap if null event 



Even t Loop 


PHA 






PushWon 


d #SFFFF 




PushPtr 


TaskRecord 




_Taa fcMas t er 




PLA 






BEQ EventLoop 




RTS 




TaskRecard 


ANOP 




what 


DS 


2 


message 


DS 


A 


when 


DS 


<■ 


where 


DS 


A 


modi f ler s 


DS 


S 


Task Da ta 


DS 


4 


TaskMas k 


DC 


!4«*Q0001F 



'.TaskMaster data 
M«*00001FFF' ;TaskMaater handles all 

When TaskMaster detects a mouse-down event, it calls the FindWindow function 
to determine in which part of a window the event occurred. The location codes 
FindWindow can return are shown in tabic 6-3. 

If FindWindow returns a $0000 event code (wNoHit), the event should be 

ignored. 
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Table 6-3: Location Codes Returned by Find Window 



Symbolic 
Name 



Code 



Meaning 



wNoHit 
win Desk 
wlnMenuBar 
wlnContent 
win D rati 
win Grow 
wlnGoAway 
wlnZoom 
wlnlnfo 
win Special 
win Desk] tern 
win Frame 
win Svs Window 



S<KXK) 

$0010 

$0011 

$0013 

80014 

$0015 

$0016 

$0017 

$0018 

80019 

$001 A 

$00 IB 

$8xxx 



Not in a window at all 

In the desktop 

In the system menu bar 

hi the window's content region 

In the window's drag region 

In the window's size box 

In the window's dose box 

In the window's zoom box 

In the window's in formation bar 

Special menu item selected (*) 

Desk accessory item selected (*) 

In any other part of the window 

In desk accessory window 



note: In the instances marked by an asterisk, FindWindaw does nol actually return these codes; they 
are returned by TaskMastei il TaskMaster is nol configured to deal with desk accessories selections 
(wlnDesklteoi) or if standard edirJngfclosing menu items are used [wlnSpcciall 



Note that if the high-order bit of the location code is .set to 1 (that is. the code is of 
the form $8xxx), the event occurred in a desk accessory. TaskMaster simply passes 
the event to the accessory by calling SysteinClick It then exits and returns a null 
event so that the application will not try la handle the event. 

Other result codes refer to application windows and are handled in different ways 
by TaskMaster. These codes are described below. 

wlnMenuBar. TaskMaster handles activity in the menu bar by calling MenuSelect 
to determine which menu item was selected. See chapter 7 for more information 
on how TaskMaster behaves beyond this stage. After processing, TaskMaster exits 
and returns a null event code. wlnMenuBar, wlnDeskltem. or wlnSpecial. 

wlnContent. If the window is not active, TaskMaster calls SelectWindow to make 
it active, exits, and returns a null event code. If it is active, TaskMaster puts a 
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pointer to the window in Task Data, exits, and returns the wlnContent code. It is 
then up to the application to handle the event in an appropriate way, by repositioning 
a cursor in a line of text or highlighting an icon, for example, li the interior ol the 
window has controls like buttons and cheek boxes, you should use the Control 
Manager to sec if they were elieked. Windows with controls are better handled by 
the Dialog Manager, as chapter S will discuss. 

wlnDrag. If the window is not active and the Open-Apple key is not down 
TaskMaster calls SelectWindow to activate the window. It then calls DragWindow. 
which causes a dotted outline of the window to move around the screen as the 
mouse moves: when the button is released, the screen is redrawn at its new position, 
TaskMaster then exits and returns a null event code. If the window is active, or the 
Open-Apple key is down, SelectWindow is not called first. 

wlnGrow. TaskMaster calls GrowWindow, which causes a dotted outline of the 
window, anchored in thr top left corner, to move in concert with the mouse. 
GrowWindow returns the new dimensions of the window, which TaskMaster passes 
to Size Window to redraw the window. TaskMaster then exits and returns a null 
event code. 

wlnGoAway, TaskMaster calls TrackGoAway to track the movement of the mouse 
until the button is released. If the button is released outside of the close box, 
TaskMaster exits and returns a null event code; otherwise, it puts the window 
pointer in TaskData, exits, and returns a wlnGoAway event code. The application 
can then either permanently dispose of the window by calling CloseWindow or just 
temporarily remove it from the screen with HideWindow, 

icInZoom, TaskMaster calls TrackZoom to track the movement of the mouse until, 
die button is released. If the button is released outside of the zoom box, TaskMaster 
exits and returns a null event code. Otherwise, it calls ZoomWindow to resize the 
window to its zoomed size or, if the window has already been zoomed, to its 
prezoomed size; TaskMaster then exits and returns a null event code. 

tuInFrame. II the window is not active, TaskMaster calls SelectWindow to activate 
the window exits, and returns a null event code. If the window is active and the 
event occurred in a scroll bar that is part of the window frame, TaskMaster calls 
TrackControl with a custom control action procedure. This action procedure per- 
forms necessary scrolling and updating of the window by calling the wGontDefProc 
procedure that was defined when the window was created. TaskMaster then exits 
and returns a null event code. If the event occurred in some other part of the frame. 
TaskMaster exits and returns the wlnFrame code. 
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wlnDesk and winlnfo. Taskmaster does nothing special for these two types of 
events. Il simply places the window pointer in TaskData and exits with the wlnDesk 
or winlnfo code, as the case may be, 

DRAWING IN A WINDOW 

Objects are drawn in a window by movin are-controlled, invisible pen around 

the screen with QuickDraw functions. These objects can be text characters, geo- 
metric objects, or random seribblings. The pen has several characteristics that can 
be set to aflccl the appearance of the object being drawn: an "ink- color and pattern. 
a size, and a transfer mode, for example. 

Note that when you draw an object, only the bits lor the pixels which tail inside 
the visible portion of the content region are actually transferred to the content 
region's memory area. Other pixels are ignored. 

The functions discussed below allect only the active QuickDraw GrafPort, which 
is not necessarily the active window. To make a particular GrafPort active and to 
adjust the coordinate origin of the GrafPort properly, use StartDrawing; 

PushLong WindowPtr ;Pointer to window 

.StartDrawx ng 

You need to call StartDrawing only when you are drawing outside a wContDefProc 
window update subroutine. 

It you do not do this, you may find that drawing operations lake place in an 
unexpected window, or in the correct window but at an unexpected position. 
StartDrawing perforins its function by calling SetPort to set the active drawing port 
and SetOrigin to set the origin to the position indicated by the values of the window's 
scroll controls. 

Before drawing in a window, it is a good idea to save the pointer to the currently 
active drawing port with Get Port: 

PHA ; space for result 

PHA 

.GetPort 

PopLong ThePort 

When you are through drawing, you can restore the original port with SetPort: 

Puahlong ThePort 
.SetPort 

It is especially important that you do this in a multi window environment to ensure 
that you do not disrupt other drawing operations. 
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Two important data structures you will use quite often with QuickDraw functions 
are points and rectangles. A point is made up of a vertical position and a horizontal 

position, as follows: 

MyPoint DS 2 -.vertical position 

DS 2 ^horizontal position 

Offsets to these two positions (from MyPoint) are given the symbolic names t (0) 
and h (2) in the STANDARD. ASM code module. So, for example, to load the 
horizontal position into the accumulator, you could use the following instruction: 

IDA NyPoint+h 

A rectangle is made up of four words representing the position of the top row, the 
left side, the bottom row, and the right side: 

MyRect DS 2 ;top 

DS 2 {left 

DS 2 ; bottom 

DS 2 ;right 

The standard symbolic names for offsets to the lour components are top (0). left (2), 
bottom 4i and right (6) and they arc included in the STANDARD. ASM code 
module. 

Note that you must change \ idMode and XMaxClamp in the STANDARD, ASM 
file to the proper values for the super high-resolution mode you want to use. For 
640-by-200 mode, set them to $80 and 640. respectively, For 320-by-200 mode, set 
them to $00and32G. 

PATTERNS AND COLORS 

A pattern is an 8-by-8 pixel image that is transferred to the screen when lines are 
drawn or shapes arc painted and filled. When a pattern is drawn in a window, it is 
blended with adjacent patterns to produce a smooth, regular pattern with no scam 
lines, A pattern can also he a solid block of color, enabling you to draw in colors 
other than black and white. 

Patterns are actually transferred to the screen only after being processed b) a 
mask. The mask is an S by S bit image (not a pixel image] that specifics which pixels 
in the pattern arc to be drawn on the screen. Only those pixels in the 8-by-S pixel 
image that correspond to I hits in the S-hy-S bit mask image are drawn. This means 
that if the mask is all Is, for example, the entire pattern is drawn to the screen. 

The QuickDraw functions that deal with patterns are summarized in table 6-4. 

A pattern is "chunky" in that each pixel is associated with either two color bits 
(640-by-2OO model or four color bits (320-by-2©0 mode). Thus, it takes either L6 
bytes or 32 bytes to define a pattern, depending on which graphics mode is active, 
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Table 6—4: QuickDraw Pattern-related Functions 



Function 


Description 


SetPenPat 


Sets the pen pattern to a specified pattern 


Get Pen Pat 


Returns the current peH pattern 


SetSolidPenPat 


Sets the pen pattern to a solid color 


SetBackPat 


Sets the background pattern to a specified 




pattern 


GetBackPat 


Returns the current background pattern 


SetSoIidBackFat 


Sets the background pattern to a solid color 


Solid Pattern 


Returns the pattern corresponding to a 




solid color 


SetPenMask 


Sets the pen mask to a specified mask 


CetPcnMask 


Returns the current pen mask 



For consistency, however, QuickDraw always allocates 32 bytes for a pattern in 640- 

by-200 mode; the second group or 16 bytes is simply a duplicate of the first group. 

The default pen pattern is a solid black color. It can be changed using SetPenPat: 



PushPtr ThePattern 

_SetPenPat 

RTS 



■.Pointer to pattern 



ThePattern 321 1 ' X01 01 01 01 < 



^Pattern definition 



A related function, GetPenPat, is called in the same way and fills the 32 bytes at 
ThePattern with the pattern definition. 

If you want to set the pen pattern to a solid color so that you can draw in color, 
use SelSolidPenPat instead: 



PuahWord #CoiorHum 
SetSolidPenPat 



; Co 1 or number 



The colors associated with each color number were given in table 6-1 at the 
beginning of this chapter. 

The difference between SetPenPat and SetSolidPenPat is that you pass a colof 
number to SetSolidPenPat. not a pattern pointer. QuickDraw takes care of creating 
the appropriate pattern lor you. The color number can be to 15 for 320-by-200 
mode or to 3 for 640-bv-2(K) mode. 
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If you want h» determine what the pattern For a solid color looks like, use 
SolidPattern: 

PushWord #CoLorMum ;coior number 

PushPtr ThePattern ^Pointer to pattern space 

_Sol idPat ter n 

RTS 

ThePattern D5 32 ;Space for pattern 

A background pattern is tfie pattern used to erase areas of a window or draw new 
areas that come into view, The default background pattern is solid white. It can be 
changed with Set Back Pat and SetSolidBackPat, functions that are called in the same 
waj as SelPcnPaf and SetSolidPenPat There is also a GctBackPat function for 
determining what the current background pattern is. 

SETTING UP THE DRAWING PEN 

Before you start drawing text in a window, you must set the pen position. This is 
the location at which text drawing will begin. There are two QuickDraw functions 
for explicitly setting the pen position: MoveTo and Move. 

MoveTo moves the pen position to a specific point in the loeaJ coordinate system 
of the window. To use it, push the horizontal and vertical components of the 
coordinate on the stack: 

PuahWord #2 ^Horizontal position 

PushWord #10 ;Vertical position 

_HoveTo 

ll'vou wish, you can combine the two PushWord operations into a single PushLong 
This is handy if the point to which you want to move is already stored in memory. 
For example, suppose GetNextEvent or TaskMaster returns a button-down event 
in the content region of a window. To move the pen position to the point specified 
in the Where field of the event record, use the following subroutine: 

PushLong Where 

_GlobalToLocal ; Switch to local coordinates 

PushLong Where -.This pushes h then v 

_MoveTo 

RTS 

Notice that because TaskMaster and GetNextEvent return a global coordinate, that 
coordinate must be converted to a local coordinate for the currently active window 
before calling MoveTo. 

When QuickDraw draws a text character, the current vertical pen coordinate 
becomes the baseline for the font. Because characters rise above the baseline, you 
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should not specify a vertical coordinate ofO for MoveTo; if you do, you will see only 
the descenders of the characters on the first line when you start drawing. 

The Move function moves the pen location in a relative way. That is. with it you 

can move the pen so man) pixels horizontally and vertically From the current pen 

on. For insliiK * \\ you want to drop down to the next text line in the window 

without changing the horizontal position {a line-feed operation), use the following 

code segment: 

PushWord #0 ; Hor 1 zonta 1 displacement 

PushWord #9 ; Vertical displacement 

_Move 

A value of 9 is used for the vertical displacement because this is the height of the 
system font. You can calculate this using the GetFontlnfo function (as described 
below). Note that positive horizontal tlispl.ii ■•■joi-iiIs are to the right and positive 
vertical displacements are downward. 

I* determine the current position ot the pen, perhaps to see if you are still inside 
the windows content region, use CetPen: 

PushPtr ThePoint ;Pojnter to point 

.GetPen 

RTS 

ThePoint DS 4 ; v , h position 

GetPen returns the position in the local coordinates of the current CrafPort. 

Setting the Pen State 

You may want to set several other pen characteristics before beginning to draw 
graphics, (The functions described below do not affect text drawing operations.) The 

important characteristics are: 

• The pen size 

• The pen transfer mode 

* The pen drawing pattern 

* The pen mask 

These four values are said to define the pen state. You can determine all their values 
at once using GetPen State: 

PushPtr PS_Record ;Ptr to pen state record 

_GetPenState 

RTS 
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PnLoc 


DS 


4 


PnSize 


DS 


I 




DS 


2 


PnMode 


DS 


2 


PnPat 


DS 


32 


PnMask 


DS 


fl 



PS_Record ANOP 

Pen position (point) 

Pen height 

Pen width 

Pen transfer mode 

Pen pattern 

Pen mask 

The parameter table passed to GetPenState is called a pen state record. 
To change the pen state, use I he following functions; 

• SctPenSize 

• Set Pen Mode 

• SetPenPat (described al 

• SetPenMask (described above) 

• SetPen State 

The size of the pen refers to the height and width of its nib, This nib hangs down 
and to the right of the current pen position. To change the pen size, say to 3 pixels 
by 5 pixels, use Set Pen Size: 



PushNord #3 
PuahWord #5 
_SetPenSize 



•, New width in pixels 
;New height in pixels 



You can determine the current pen size with GetPenSizc: 

PushPtr PenSlreLoc -^Pointer to result space 

_GetPenSi ze 

RTS 

PenSizeLoc DS 4 
GetPenSize returns the width and height at PenSizeLoc. 

The pen mode refers to the way in which QuickDraw combines the pattern flowing 
out of the pen with the pixels on the screen. The result of the combination is 
displayed on the screen. The different modes are summarized in table 6-5. (Note 
that some of these modes are for text drawing only.) 

To change several pen characteristics at once, call SetPenStatc by passing it a 
pointer to a filled-in pen state record. 

If you have changed several pen characteristics and you want to return to the 
standard pen state, call PenNormal (no parameters). It sets the pen size to 1 by 1, 
the pen mode to COPY, the pen pattern to black, and the pen mask to all Is. 
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Table 6-5: 


Tin 


QuickDraw Transfer Modes 




Transfer Mode 


Sijmholie 
Name 


Description 


$0000 




COPY 


Pixels are copied directly to th 
screen. 


$0001 




OR 


Pixels are logically ORed with 
the screen pixels. 


$0002 




XOR 


Pixels are logically exclusive- 
ORed with the screen pixels. 


$0003 




BIC 


Pixel bits which are set to 1 
cause corresponding pixels on 
the screen to be cleared to 0. 


$0004 




foreCOPY 


Fead only: Foreground pixels 
arc copied directly to the 
screen. 


$0005 




foroOR 


Text only: Foreground pixels 
arc logically ORed with the 
screen pixels. 


$0006 




foreXOR 


Text only: Foreground pixels 
are logically exclusivc-ORed 

with the screen pixels. 


$0007 




fareBIC 


Text only; Foreground pixel 
bits which are set to 1 cause 
corresponding pixel bits on the 
screen to be cleared to 0, 


$8000 




notCOPY 


The pen pattern or text is 
inverted, then copied directly 
to the screen. 


$8001 




notOR 


The pen pattern or text is 
inverted, then ORed with the 
screen pixels. 


$8002 




notXOR 


The pen pattern or text is 
inverted, then logically 
exclusive-ORed with the screei 
pixels. 
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Table 6-5: Continued 





Symbolic 




Transfer Mode 


Name 


Description 


$8003 


notBIC 


The pen pattern or text is 
inverted, then those pixel bits 
which are set to 1 cause 
corresponding pixels on the 
screen to be cleared to 0. 


$8004 


notforeCOPY 


Text only: The character 
redans!*-' is inverted, and the 
pixels that arc on arc copied 
directly to the screen. 


$8005 


nolforeOR 


Text only: The character 
rectangle is inverted, and the 
background pixels are logical ly 
ORcd with the screen pixels. 


$8006 


notforeXOR 


Text only: The character 
rectangle is inverted, and the 
background pixels are logically 
exclusive-ORed with the screen 
pixels. 


$8007 


notibreBIC 


Text only: The character 
rectangle is inverted, and the 
background pixels which are set 
to 1 cause corresponding pixel 
bits on the screen to be cleared 
toO. 



FONT CHARACTERISTICS 

A font is a set of characters having the neral ornamental design. One font. 

called the system lout, is stored in the GS ROM and is always available for use by 
the QuickDraw text-drawing functions. Other Fonts may be defined and stored in 
the SYSTEM/FONTS/ subdirectory on the hoot disk. They can be loaded into 
memory and made available to an application using the Font Manager. QuickDraw 
can draw characters in any available font, hut it will use the system font unless you 
specify otherwise. 

Although QuickDraw has a few font-related functions, you should use the more 
powerful Font Manager functions instead. To start up the Font Manager, use 
FM Startup: 



Font Characteristics 193 



PushWord MylD jProgram ID (from MflStartup) 

PushWord DPAddr ;Address of one page in bank $00 

FM5 tar t up 



The Font Manager requires the presence of most GS tool sets, including the rarely- 
used List Manager. Make sure they are all loaded before calling FM Startup. 

FMStartup scans the SYSTEM/FONTS/ subdirectory of the boot disk and makes 
a list of the font families it finds there. A font family is a general font type such as 
Helvetica, Courier, or Venice, Tin- default system font is called Shaston. 

A font of a particular family, size, and style is described by a lontlD long v 
Here is its structure; 



• bits 00-15 : font family number 

• bits 16-23 : font style byte 

• bits 24-31 : font size byte 



The family number is the number the Font Manager assigns to the font when it 
puts the font in its font list. Bits in the style byte affect the style of tine font (bold, 
italic, underline, outline, or shadow); style bytes are described below in the discus- 
sion ol SetTextFace. The font size is the point size of the font (1 point = 1/72 ol an 
inch). 

The user can install a new font relatively easily, at least if the application calls 
ChooseFoiit to bring up a standard font selection dialog box: 

PHA ;space for result 

PHA 

PushLong TheFontlD ;fontID of current font 

PushWord #0 ; - list all fonts 

_ChooseFon t 

PopLong WewFontlD ; Result 15 new fantlD 

Push zero instead of TheFontlD to select the system font. 

The form of the font selection dialog box is shown in figure 6-8, It consists of a 
scrollable window that holds a list of loot names for selection, checkboxes for 
selecting the font style, and a scrollable window that holds a list ol point sizes that 
are available, There is also an edit box for typing in any other point size to which a 
font should be scaled: scaled fonts can look ragged, however, 

Choosel-oni • irns the IbntlD for the font selected, or if the dialog box was 
canceled. 
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Figure 6-8. The Font-selection Dialog Box 



Font: 



Courier 
Geneva 



Shasto 



Times 



ca 



a 



k 



e: 



Size: 



^Plain 

jBold 
D Italic 

] Underline 
D Outline 
Q Shadow 



8 ffl 



Other 
Size: 







(Cancel) 



OK 
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Figure 6-9. The Characteristics of an Apple lies Font 
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To make the selected (tint the current font, so thai it will be used by QuickDraw 
text drawing functions, call lnstallFont: 



PushLong NewFontID 
PushWord #0 
_I natal IFont 



5 font ID of desired font 
; = enable scaling 



The second parameter controls whether font sealing is enabled If bit is 1, scaling 
is not enabled. 

When you are through using the new font, you can make the system font the 

current font again with the LoadSysFont function (no parameters), If you at; never 
going to use the new font again, make it purgeable with Setl'urgeStat: 



PushLong NewFontID 
PushWord #%0001 0000 
_5etPurgeStat 



; font ID of font 
;bit 4 = 1 (purge] 



Bit 4 of the second parameter controls whether the specified font is to be purgeahlo 
(1) or not purgeable (0). 

Font Definitions 

As shown in figure 6-9, each character in a iont is defined inside a rectangular grid, 
called the font rectangle, which encloses the largest character in the font. Another 
rectangle, the character rectangle, is the smallest rectangle that can enclose the 
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outline of the character. The size of this rectangle will vary-, depending on the size 
of the character. 

Those points in a character rectangle that are highlighted are called foreground 
points, because they define the actual shape of the character. The other points are 
background points. When a character is transferred to a GrafPort, the foreground 
points become black pixels and the background points become white pixels, although 
you ran change these default colors with SetBackColor and SetForeColor if you 
wish. The colors are defined by either a 2-bit number (64O-by-2O0 mode) or a 4-bit 
number (32()-hy-2(X) mode), so there are either four or sixteen colors to choose from. 

Each character in a font is defined relative to two reference points, the baseline 
and the character origin. The baseline is an imaginary line on which the character 
rests it serves much the same purpose as a line on a piece of notepaper. The number 
of pixel lines between the baseline and the top of the font rectangle is the ascent 
Hie number of lines between the baseline and the bottom of the font rectangle is 
the descent — this is where the descenders of characters such as g, y, j, p, and q 
appear. 

The character origin marks the position in the character rectangle that is aligned 
with the pen position before the character is drawn. The widMax of a font is the 
maximum number of pixels between the character origins of two successive char- 
acters. For a proportional font, such as the system font, the actual widths of most 
characters are less than this. You can, however, tell QuickDraw to draw system font 
characters that are all widMax pixels wide using SetFontFlags; 

PushWord #1 -, 1 = f i xed -wi d th , =propor t ional 

_SetFon tF lags 

To return to proportional mode, pass a to Set I- on U' 'la^s. Yon probably will not 
use fixed-width characters very often, however, because the gaps between characters 
are large and unsightly. Von also cannot fit as many characters across the width of 
the screen. 

The leading of a font is defined as the number of blank lines between the descent 
line and the bottom of the font rectangle. This area acts as a spacer between 
successive lines of text. GetFontlnfo returns the ascent, descent, widMax* and 
leading of the currently active Font in a four-word font information record. For the 
system font, the results are as follows: 

• ascent 7 

• descent 1 

• widMax 12 

• leading 1 

Font Characteristics 197 



The subroutine below, which incorporates CetFontlnfo, can be used tu move the 
pen position to the next line in the window; 

; vertical field offset 
:Pointer to font record 



v 


GEQU 





CRLF 


START 






PuahPtr 


Fl Record 




_OetFon 


L Jnfo 




CLC 






LDA 


Ascent 




ADC 


De scent 




ADC 


Leading 




STA 


FontHeight 




PushPtr 


PenPo5 




_GetPen 






CLC 






LDA 


PenPoa+v 




ADC 


FontHei gh t 




PEA 


2 




PHA 






_MoveTo 






RTS 




F I Record 


ANDP 




Ascent 


D5 


2 


Descent 


DS 


I 


Wi dflax 


3b 


2 


Lea d i nq 


DS 


2 


FontHeight 


D5 


2 


PenPo5 


DS 
END 


'• 



^Pointer to a point 

;Get current pen position 



;&et current vertical 
\ Add line he i ght 

-.horizontal {left edge) 
■vertical (next line) 



•.Font information record 



; point (v ( h) 



This subroutine adds ascent, descent, and leading together to calculate the height 
of the font. It then adds the height to the current vertical pen position to determine 
the vertical position of the next baseline. Finally, it calls MoveTo to position the 
pen at the left side of this line. 

You can assign certain typeface attributes to a font using the SetTextFace function, 
The five attributes currently defined are bold, italic, underline, outline, or shadow 
or any combination of the five. Hits in the word parameter passed to SetTextFace 
correspond to attributes as shown in figure 6-10. If all the bits are 0, the typeface 
is called plain 

For example, to switch the typeface to bold, execute the following code segment: 

PushWord #*D0QQQGQ1 itextface word 

^SetTex tFace 
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Figure 6-10. The Style Byte Used by SetTextFaee 



7 


6 


5 


4 


3 


2 


1 






not used 



bold 

italic 
underline 



Note that some fonts, including the system font, may no! support all of these 
attributes, 

GetTextFaee returns the current lextface word: 



PHA 

,&e t Tex t Face 

PLA 



*, space for result 
;Oe t the resul t 



DRAWING CHARACTERS 

To print a single character in a window, position the pen with Move or MoveTo. 
Then push the ASCII code for the character on the stack and call DrawChar: 



PushWord #$41 
_DrawChar 



;ASCII code for "A" 



As in all QuickDraw text drawing functions, the ASCII code for standard characters 
must have hit 7 cleared to (J. See appendix I for a description of the ASCII encoding 
scheme. The system font assigns various foreign characters, monetary symbols, and 
common icons to the 128 codes that have bit 7 set to 1. 

There arc three other "Draw" functions for drawing sequences of characters stored 
in memory: DrawString, DrawCString. and DrawText. The one to use depends on 
whether the sequence begins with a length byte (a Pascal- type string), ends with a 
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zero byte (a (type string), or is an arbitrary sequence of characters with no length 

indicator (text)* 

Three subroutines showing how to use these drawing functions are given below: 

DrawSubl PushPtr MyPString -.Pointer to atnng 

_DrawStr ing 

RTS 

DrawSubl PushPtr MyCString ;Pointer to string 

_DrawCSt r 1 ng 
RTS 

DrawSubS PuahPtr MyText jPoititer to string 

PushWord #14 -.length 

_DrawTex 1 
RTS 

MyPString DC 11 M6' ; length 

DC C'A Pascal string.' ',the characters 

MyCString DC C'A C string. 1 }the characters 

DC 11*0' ; trai 1 ing 00 

MyText DC C'Thia is a text string.' 

Notice that for DrawText, you identify the portion of the text to be displayed by 
specifying a starting position and the number of characters with which you want to 
work. This is not necessary for DrawString or DrawCString. because the length is 
known and the entire string is always printed. 

If von use Pascal-type strings quite often, you will find it convenient to define 
them with a macro called STR, STR is useful because it automatically calculates the 
length of the string and inserts it before the string's character codes. You do not 
have to count the characters yourself. Here is how to define the string "A Pascal 
string" using STR instead of two DC directives: 

MyPString STR 'A Pascal string' 

A definition for the STR macro is given in listing 6-3, 

It is important to realize that the pen position automatically advances along the 
line as you draw characters There is no need to set it explicitly with Move or 
MoveTo unless you want to move to another line or to a non-adjacent position on 
the same line. 
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Note that none of the text-drawing functions react to control characters in standard 
ways. If you pass a carriage return code ($0D) to DrawChar, for example, the 
drawing position does not automatically move to the left side of the next line in a 
window; instead, an inverse question mark character appears on the screen (indi- 
cating that there is no symbol for the character in the font definition). It is up to 
the application to intercept control characters and handle them appropriately. 

Text Measuring 

It is often convenient to know the width of a character, or a series of characters, 
before drawing. Knowing the width, you can easily center the text or determine if 
there will be enough room to display it on the current line. The program in listing 
6-4 shows how to center a line of text in a window, for example. 

QuickDraw has a set of text measuring functions you can use to determine widths: 

• CharWidlh (For a single character) 

• Text Width (for a sequence of characters) 

• StringWidth (for a string preceded by a length byte) 

• CStringWidth (for a string followed by a S00 byte) 

To use these functions, first push a dummy word on the stack to reserve space for 
the result (the width in pixels), and then push the ASCII code for the character 
(CharWidth) or a pointer to the text or string (TextWidth. StringWidth, 
CStringWidth). For TextWidth. you must also push the length of the text string. 
Finally, call the function and pop the result from the stack, 

Text Color 

Using SetForcCoIor and SetBackColor, you can set the foreground and background 
color of text you draw in a window. Both require a parameter word that contains 
the color number to which you want to switch. In 640-by-200 mode, this number 
can be to 3; for 32G-by-200 mode, it can be to 15. 
Here is how r to use SetForeColor and SetBackColon 

PushWord #ColorNum ;Push new color number 

.SetForeColor ; (or SetBac kColor J 

To determine the current color characteristics of the font, use GetForeColor and 
GetBackColor They return the color number on the stack: 
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PHA jspace for result 

_OetBackColor 

PLfl 

STfl TheCdlor ;pop the result 



The default background and foreground colors are white and black, respectively. 

The program in listing 6-5 shows how to display text in all L6 colors in 320-by- 
200 mode using SctForeColor. 



Transfer Modes for Text 

A transfer mode refers to the technique QuickDraw uses to draw a text character 
on the screen, The mode defines how QuickDraw is to combine a pixel in the 
character with the corresponding pixel in the screen buffer. 

The possible transfer modes were described in table 6-5. The default mode is 
COPY, which causes the pixels in the character rectangle to replace the correspond- 
ing pixels on the screen. 

Another particularly useful mode is foreXOR. If you use this mode, you can draw 
text on any background, and then erase the text and redraw the background simply 
by redrawing the text again at the same position. 

To set the transfer mode, use SetTextMode: 

PuahWord #TextMode ;Text transfer mode cade 

^SetTextMode 

You can determine what the currently active mode is using GetTextMode: 

PHA jspace for result 

GetTextMode 
PLA 
STA TheMode ;Pop the mode code 

It is hard to visualize the effect of some of the transfer modes. It is best to write a 
short program that uses different modes to draw text on differently colored back- 
grounds . 



DRAWING LINES AND SHAPES 

QuickDraw has several functions for drawing objects other than characters or text 
strings. You can use these functions to draw lines, rectangles, arbitrary regions, 
polygons, ovals, round rectangles, and arcs. 

202 Windows and Graphics 



Lines 

You can draw straight lines with the Line and LineTo functions. LineTo draws a 
line from the current pen location to the specified point: 

PushWord #43 ;Horizontal position 

PushWord #22 ^Vertical position 

_LineTo ;Draw the line 

With Line you can draw a line thai terminates at a position that is relative to the 
current pen position: 

PushWord #10 -.Horizontal displacement 

PushWord #5 '.Vertical displacement 

.Line 

Positive horizontal displacements move the pen to the right. Positive vertical dis- 
placements move if down. 

After either Line or LineTo is called, the pen position moves to the end ol the 
new line. 



Shapes 

QuickDraw uses five fundamental drawing operations to manipulate the shapes it 

supports: 

Framing — drawing an outline of the shape. 

Painting — filling the interior of a shape with the current pen pattern. You can 
set the pattern to a particular color using SetSolidPeuPat or to any arbitrary' 
pattern using SetPenPat 

Erasing — replacing the interior of a shape with the background pattern. You 

can set the background pattern using SctSolidBaekPal or SetBackPat. 

Inverting — inverting the pixels inside a shape. 

Filling — filling the interior of a shape with a specified pattern. 

The specific shape-drawing functions for objects are summarized in table 6—6. 
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Table 6-6; QuickDraw 11 Shape-drawing Functions 



Function 


Description 


FrameReet 


Draws the outline of a rec tangle 


FrameRgn 


Draws the outline of a region 


FramePoly 


Draws the outline of a polygon 


FrameOval 


Draws the outline of an oval 


FrameRRcet 


Draws the outline ol a round rectangle 


FrameArc 


Draw r s the outline of an arc 


PaintRect 


Fills the interior of a rectangle with 




the current pen pattern 


PaintRgn 


Fills the interior of a region with the 




current pen pattern 


PaintPoly 


Fills the interior of a polygon with the 




current pen pattern 


PamtOval 


Fills the interior of an oval with the 




current pen pattern 


PaintRRecl 


Fills the interior off a round rectangle 




with the current pen pattern 


PaintArc 


Fills the interior of an arc (a wedge) 




with the current pen pattern 


Erase Rett 


Fills the interior of a rectangle with 




the current background pattern 


EraseRgn 


Fills the interior of a region with the 




current background pattern 


Erase Poly 


Fills the interior of a polygon with the 




current background pattern 


Erase Oval 


Fills the interior of an oval with the 




current background pattern 


EraseRRect 


Fills the interior of a round rectangle 




With the current background pattern 


Erase Arc 


Fills the interior of an arc {a wedge) 




with the current background pattern 
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Table 6—6: Continued 



Function 


Description 


InvertRect 


Inverts the pixels in a rectangle 


lnvertRgn 


Inverts the pixels in a region 


InvertPoly 


Inverts the pixels in a polygon 


InvertOval 


Inverts the pixels in an oval 


InvertRRect 


Inverts the pixels in a round rectangle 


Invert A re 


Inverts the pixels in an arc (The arc is 
defined by a starting angle and an 

angular extent.) 


FillRect 


Fills the interior of a rectangle with a 
specified pattern 


FillRgn 


Fills the interior of a region with a 
specified pattern 


FillPoly 


Fills the interior of a polygon with a 
specified pattern 


FillOval 


Fills the interior of an oval with a 
specified pattern 


FillRRect 


Fills the interior of a round rectangle 
with a specified pattern (The 
curvature of the corners can also be 

set.!' 


FillArc 


Fills the interior of an are with a 
specified pattern (The are is defined 
by a starting angle and an angular 
extei 1 1 



To draw the outline (if a rectangle in a window, call Frame Rect by passing a pointer 
to the definition of the rectangle: 



PushPtr TheRect 
_FrameRec t 
RTS 



■♦Pointer to rectangle 



TheRect DC I 2 ' 30 ,20 , 1 00 , 1 20 ' jTop, left, bottom, right 
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Notice that the coordinates for the rectangle arc specified in top, left, bottom, right 
iTLBR) order. 

To erase the rectangle, use EraseRcct: 

PushPtr TheRect -.Pointer to rectangle 

_Era seRect 

To invert the pixels inside the rectangle, use InvcrtRcct: 

PushPtr TheRect ;Pointer to rectangle 

_ InvertRect 

To rill the interior of a rectangle with the current pen pattern, use PaintReet: 

PushPtr TheRect -.Pointer to rectangle 

.PaintReet 

To fill it with any arbitrary pattern, use FillKect: 

PushPtr TheRect {Pointer to rectangle 

PushPtr ThePattern ;Pomter to pattern definition 

^FillRect 

The pattern definition defines an 8 by 8 pixel grid, as explained in the section above 
called "Patterns and Colors " 

The corresponding shape-drawing functions for other shapes have suffixes of Rgn 
(regions). Poly polygons). Oval (ovals). RRect (round rectangles), and Arc (arcs). 
The functions are called in much the same way as the corresponding rectangle 
functions, but instead of pushing a pointer to a rectangle, push the following 
information: 

For regions, a handle to the region 

For polygons, a handle to the polygon definition 

For ovals, a pointer to the imaginary rectangle enclosing the oval 

For round rectangles, a pointer to the imaginary rectangle enclosing the round 
rectangle, followed by two words describing the width and height of the ima- 
ginary oval inscribed in each corner 

For arcs, a pointer to the imaginary rectangle enclosing the imaginary oval of 
which the arc forms a part, followed by two words describing the starting angle 
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of the are (in degrees} and the extent of the arc (in degrees). Angles are measured 
relative to a vertical axis moving up from the center of the oval 



Note that the interior of an arc is actually the wedge bounded by the arc and the 
imaginary lines from the ends of the arc to the center of the enclosing oval. 



Polygons 

In the previous section, we came across a shape called a polygon. A polygon, as any 
student of geometry can tell you, is an enclosed, multisided object. To define a 
polygon with QuickDraw, first open a polygon record by calling OpenPoly, as follows: 

PHfl ;Space for result (handle) 

PHA 

_0penPoly 

PopLong PoiyHndl >Pop handle to polygon 

The next step is to draw the outline of the polygon by making a series of calls to 
LineTo until the entire outline has been traversed. These lines are not actually 
displayed on the screen; the LineTo parameters are just stored in the polygon 
record. Finally, coll ClosePoly (no parameters! to complete the polygon creation 
process. 

Using the polygon handle returned by OpenPoly, you can perform all the standard 
QuickDraw drawing operations, such as FrarnePoly, PaintPoly, and Fill Poly. The 
polygon you draw appears at the same position at winch it was defined, unless you 
shift its position with the OffsetPoly function: 

PushLong PoiyHndl '.Polygon handle 

PushWord #horiz ; Hor i zont a 1 displacement 

PushWord #vert ■, Vertical displacement 
_Df f aetPoly 

Positive displacements are clown and to the right. 

When you do not need the polygon any more, dispose of it by calling KillPoly; 

PuahLong PoiyHndl -.Handle to polygon record 

_Ki UPoly 

This frees up the memory space QuickDraw previously allocated lor the polygon 

record, 
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An example of how to deal with polygons is given in listing 6-6. This code defines 
a pentagon and draws it on the screen, 

CREATING AN APPLICATION WITH WINDOWS 

Now that methods of creating windows and drawing characters and objects have 
been covered, it is time to put it all together. The program in listing 6-7 shows how 
to implement many of the important functions that have been discussed in this 
chapter. It also illustrates how to deal with scroll controls and update procedures. 

This program, called TextReader, loads a readable text file into memory from 
disk and lets you view any part of it using the right and bottom scroll controls of a 
window. 

In this program, the file is loaded into memory using several ProDOS 16 com- 
mands thai have not been covered yet— OPEN, NFWLINE, GET.EOF, READ, 
and CLOSE. These commands will be discussed in chapter 10, although you can 
probably guess what most of them do already. The program also uses an SFGetFile 
dialog box to request the name of the file to be loaded. This dialog box will also be 
discussed in chapter 10. 

After loading a file from disk. TextReader uses NewWindow to create a window 
with scroll controls in its window frame. It does this by setting the right and bottom 
scroll bits of the window frame word in NewWindow's parameter list. It also sets 
the bits for a title bar, zoom box, and grow box. 

Several Other items in the window parameter list must be set up for any window 
containing scroll controls. First, you must specify the number of lines the content 
region of the window should scroll when the mouse is pressed in different parts of 
the scroll controls (except the thumbs}. TextReader is designed to scroll one entire 
line of text if the mouse is pressed in the up or down arrow of the right scroll 
control. Thus, a value of 9, the pixel height of the system font TextReader us« i 
stored in the appropriate position in the parameter table. A convenient scrolling 
distance for activity in the left or right arrow of the bottom scroll bar is 12 pixels, 
because this is the maximum width of a character in the system font. 

The scrolling distance for activity in the page-up or page-down regions of the 
right scroll bar is the full height of the content region, minus the height of one line 
(9 pixels). The height of one line is subtracted to ensure that all lines are not scrolled 
oil' the screen — this makes it easier for the user to keep track of a scrolling operation. 
Similarly, the scrolling distance for the page-left and page-right regions of the bottom 
scroll bar is set to the width of the content region, minus 12. Roth of these distances 
are updated every time Task Master returns a non-null event in case the window 
has been resized by zooming or by dragging the grow box. 

The next step is to specify the maximum height and width, in pixels, of the hlock 
ol text being displayed in the window. This information is needed so that the size 
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of the scroll control thumbs and page regions can be calculated, For example, the 
ratio of the height of the thumb in the righl stroll bar lo the height of" the entire 
scroll bar is the same as the ratio of the height of the content region to the height 
ot tin 1 document. 

In Text Reader, the maximum width is sit to 960 on the assumption that no line 
will be wider than 80 characters (remember, the maximum width of a single character 
is 12 pixels! The maximum height is set initially to an arbitrary 1,024, but this is 
changed once the file has been loaded and its height is known. TextReader calculates 
the height by scanning the loaded file for end-of-line characters (carriage returns! 
and adding 9 to the DocSize variable for every one it finds. An arbitrary figure oi 
20 pixels is added to the height to give the document a bottom margin. 

Another parameter you must set before calling NewWindow is the one holding 
the position within the document that corresponds to the top left comer of the 
content region. NewWindow uses this parameter to determine where to draw the 
thumbs of the scroll bars. TextBeader sets this position to 0,0 so that the top line 
of the text will appear at the top of the window when the content region is updated 
for the first time. 

The last scroHing-r elated parameter that must be set is the one containing the 
address of the subroutine- that TaskMaster calls when the window needs updating. 
Every scrolling operation forces a screen update, because every such movement 
brings a new portion of the document into view. This subroutine is called Wind- 
Update in the TextBeader program and is responsible lor redrawing the content 
region of the window 

Before TaskMaster calls the Windtpdatc screen updating subroutine, it uses 
SetOrigin to assign the top left-hand corner of the window's content region to the 
position within the document given by the values of the scroll controls. This means 
that the content region is alread) aligned with the active portion of the document. 

The easiest way to update the content region is simply to redraw the entire 
document: because drawing is dipped to the content region, you will not mess up 
other areas of the screen. This is not a satisfactory method for large documents, 
however, because it is very slow — after all. you must go through the charade oJ 
redrawing portions of the document that do not actually appear in the window. 

A much faster alternative, the one used by TextReader. is to redraw onlv that 
portion of the document appearing In the content region. To locate the first line 
that will appear in the content region. TextReader first zeroes a counter, then adds 
9 {the line height) to the counter for eaeli eud-of-line character (carriage return! it 
finds while scanning through the document from the beginning. When the counter 
becomes greater than the vertical position of the top of the content region (stored 
at Port Rect + top), the search is over. Eaeli line in the document is then drawn (with 
DrawText) until the pen position is one clear line below the bottom of the content 
region. (Carriage retorn codes arc handled by calling CKLF to move the invisible 
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drawing pen to the left side of the next line.) TextReader does not bother to do 
range checking on the sides, although you could add code to do this to make updates 
happen a bit faster. 

TaskM aster calls the update handler with a JSL instruction, so the handler ends 
with an RTL instruction. Do not end with an RTS instruction as you would if the 
routine was called with JSR. Another tip on writing an update handler relates to 
the direct page; the active direct page when TaskMaster calls the update handle] is 
not the direct page the application uses. If you must access data in the application s 
direct page, perhaps to use pointers you have previously set up in direct page. 
switch to the direct page first. The WindUpdate subroutine does this so that it can 
access the direct page pointer to the text block. 

Once TextReader defines the window and loads the text Hie. it enters a short 
TaskMaster event loop Because TaskMaster automatically takes cart- of all mouse- 
down events in the scroll bars and handles all update events, the application does 
Oat have to do anything special to support scrolling. 



REFERENCE SECTION 

Table R6-1: The Major Functions in the QuickDraw II Tool Set (§04) 





Function 


Shirk 


Description of 


Function A'u 


$ umber 


Parameters 


Parameter 


CharWidth 


Sj vs 


result (W) 


Width of character in pixels 






Char (W) 


The character 


CloseFoly 


$C2 


[no parameters] 




CStringWidth 


$AA 


result (W) 


Width of string in pixels 






TheCString (L) 


Ptr to C-style text string 


DrawChar 


SA1 


Char (W) 


ASCII code for character 


DrawCStiing 


SA6 


TheCString (L) 


Ptr to C-style text string 


DrawString 


$A5 


ThcStriug (L! 


Ptr to text string 


DrawText 


SAT 


TheText (L) 


Ptr to start of text 






Counl (W) 


Nimiher of characters to draw 


E rase Arc 


S64 


Rectangle (L) 


Ptr to rectangle 






StartAngle (W) 


Starting angle 






A re Angle (W) 


Extent of angle 


EraseOvaJ 


Sn\ 


Rectangle 1 , 


Ptr to rectangle 
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Function Name 


Function 
Number 


Stack 

Parameters 


Description of 
Parameter 


Erase Poly 


$BE 


PolyHndl (L) 


Handle to polygon 


EraseRect 


$55 


Rectangle (L) 


Ptr to rectangle 


EraseRgn 


$7B 


RgnHndl (L) 


Handle to region 


EiaseRRect 


$5F 


Rectangle (L) 


Ptr to rectangle 






OvalWidth (W) 


Width of corner oval 






OvalHeight (W) 


Height of comer oval 


FillArc 


$66 


Rectangle 1 1 . 


Ptr to arc's rectangle 






StartAngle (W) 


Starting angle 






Arc-Angle (W) 


Extent of angle 






Pattern Ptr (L) 


Ptr to fill pattern 


FillOval 


$5C 


Rectangle (L) 


Ptr to oval's rectangle 






Pattern Ptr (L) 


Ptr to fill pattern 


FillPoly 


SCO 


PolyHndl iL: 


Handle to polygon 






Pattern Ptr (L) 


Ptr to fill pattern 


FillRect 


$57 


Rectangle (L) 


Ptr to rectangle 






Pattern Ptr (L) 


Ptr to the fill pattern 


FillRgn 


$7D 


RgnJIndl (L) 


Handle to region 






Pat tern Ptr (L) 


Ptr to the fill pattern 


FillRRect 


$61 


Rectangle (L) 


Ptr to tract's rectangle 






OvalWidth (W) 


Width of corner oval 






Oval Height (W) 


Height of corner oval 






Pattern Ptr (L) 


Ptr to fill pattern 


Frame Arc 


$62 


Rectangle (L 


Ptr to rectangle 






StartAngle (W) 


Starting angle 






Arc-Angle (W) 


Extent of angle 


FrameOval 


$58 


Rectangle (L) 


Ptr to rectangle 


Frame Poly 


$BC 


PolyHndl (L) 


Handle to polygon 
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Function 


Stack 


Description of 


Function Name 


Number 


Parameters 


Parameter 


E H >arneRect 


$53 


Rectangle (L) 


Ptr to rectangle 


Frame Rgn 


S79 


RgnHndl (L) 


Handle to region 


Frame RRect 


S5D 


Rectangle (L) 


Ptr to rectangle 






OvalWidth (W) 


Width of corner oval 






OvalHeighttVVJ 


Height of corner oval 


GetBackColor 


$A3 


result (W) 


Background color number 


GetBackPat 


$35 


PatternPtr (L) 


Ptr to the background pattern 


GctColorEntry 


$11 


result (W) 


Color entry value 






TableNuin (W) 


Color table number 






EntryXum (W) 


Color number 


GetCoiorTable 


SOF 


TableNum (W) 


Color table number 






ColorTblPtr (L) 


Ptr to space for color table 


GetFontlnfb 


S96 


FIRectPtr (L) 


Ptr to font info record 


GetForeColor 


$A1 


result (W) 


Foreground color number 


GetPen 


$29 


PointPtr (L) 


Ptr to space for point result 


Get Pen Mask 


$33 


MaskPtr (L) 


Ptr to space for pen mask 


GetPen Mode 


$2F 


result (W) 


Current pen mode 


GetPen Pat 


S31 


PatternPtr (L) 


Ptr to current pen pattern 


GetPenSize 


$2D 


PointPtr (L) 


Ptr to width/height result 


GetPen State 


$2B 


PenStalePtr (L) 


Ptr to space for PS record 


GetPort 


$1C 


result (L) 


Ptr to current GrafPort 


GetPortRect 


$20 


RectPtr (L) 


Ptr to space for rect result 


GetSCR 


$13 


result (W) 


Scanline control byte 






Scan Line [\\ i 


Scan line number 


GetTextFaee 


$9B 


result (W) 


Current textface word 


GetTextMode 


$9D 


result (W) 


Current text drawing mode 


GlobalToLocai 


$35 


PointPtr (L) 


Ptr to point to convert 
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Function 


Stack 


Description of 


Function Name 


Number 


Parameters 


Parameter 


InitColorTaWe 


|0D 


ColorTblPtr (L) 


Ptr to space For color table 


Invert Arc 


$65 


Rectangle (L) 


Ptr to arc's rectangle 






StertAngle (W) 


Starting angle 






ArcAngle iU'i 


Extent of angle 


InvertOval 


$5B 


Rectangle (L) 


Ptr to ovals rectangle 


InvertPok 


$BF 


PolyHndl (L) 


Handle to polygon 


InvertReet 


$56 


Rectangle (L 


Ptr to rectangle 


[flvertRgn 


$7C 


RgnHndl (L) 


Handle tn region 


Invert RReet 


$60 


Rectangle <L) 


Ptr to rreet's rectangle 






OvalWidth (W) 


Width of corner aval 






OvaLHeight (W) 


Height of corner oval 


KillPoly 


$C3 


PolyHndl 


Handle to polygon 


Line 


S3D 


hOffset (W) 


Horizontal offset 






vOffset (W) 


Vertical offset 


LineTo 


$3C 


hPos i\\ i 


Horizontal position 






vPos (W) 


Vertical position 


LocalToGlobal 


$84 


Point Ptr (L) 


Ptr to point to convert 


Move 


$3A 


DispX (W) 


Horizontal displacement 






DispV (W) 


Vertical displacement 


MoveTo 


$3B 


HorizPos 


Horizontal position 






VertPos (W) 


Vertical position 


OffselPoly 


S( 4 


PolyHndl (L) 


Handle to polygon 






hOffset W 


Horizontal displacement 






vOffsel (W) 


Vertical displacement 


Open Poly 


SCI 


result (L) 


Handle to polygon 

n _J" C~_*j n _ nil 
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Function 


Stack 


Description of 


Function Name 


Number 


Parameters 


Parameter 


PaintAre 


$63 


Rectangle (L) 


Ptr to rectangle 






Start Angle (W) 


Starting angle 






AreAngle (W) 


Extent of angle 


PaintOval 


$59 


Rectangle (L) 


Ptr to rectangle 


PaintPoly 


SBD 


PolyHndl (L) 


Handle to polygon 


PaintRect 


$54 


Rectangle (L) 


Ptr to rectangle 


PaintRgn 


$7A 


RgnHndl (L) 


Handle to region 


PaintRRect 


$5E 


Rectangle (L) 


Ptr to rectangle 






OvalWidth (W) 


Width of comer oval 






OvalHeight (W) 


Height of corner oval 


Pen Normal 


S36 


[no parameters] 




QDShutDowu 


$03 


[no parameters] 




QDStartup 


$02 


DPAddr [W] 


Address of 3 pages in bank 






MasterS CB (W) 


88000 = 640/SOOOO = 320 






MaxWidth (V\ 


Size of largest pixel map 






UserID(W) 


ID tag for memory allocation 


SetAHSCBs 


$14 


NewSCB(W) 


New SCB value for all lines 


SetBackColor 


8A2 


ColorNum i.VVj 


Background color number 


SetBackPat 


S34 


Pattern Ptr (L) 


Ptr to new background 
pattern 


SctColor Entry 


$10 


TableNumber (W) 


Color table number {0-15} 






Entry Number 


Color number in table (0-15) 






(W) 








NewColor(W) 


\r\v color value 


SetColorTable 


#0E 


TableNumber (W) 


Color tabic number (0-15) 






1 1 iTblPtr (L> 


Ptr to new color table 
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Function Name 
SetFontFlags 

SetForeColor 

SetOrigin 

SetPenMask 
SetPenMode 
SetPenPat 
SetPenSize 

SetPen State 

Set Port 

SetPortRect 

SetSCB 



SetSolidBackPat 838 



h'unction Stack 
Number Parameters 



Description of 
Parameter 



$98 FontFlag W i 

SAO ColorNum (W) 

823 xOrigin (W) 
yOrigin (W) 

$32 MaskPtr | L) 

S2E PenMode (W) 

$30 PatternPtr (L) 

$2C PenWidth (W) 

Penlleight (W) 
$2A PenStatePtr (L) 

$1B PortPtr (L) 

$1F Rectangle (L) 

$12 ScanLine (W) 

NewSCB iWi 
ColorNum (W) 



SetSolidPenPat 
SetTextFace 
SetTcxtMode 
SoIidPattern 

StringWidth 



S37 



$9C 



ColorNum (W) 
Text Face (W) 
Text Mode (W) 
ColorNum (W) 
PattemPlr (L) 
result (W] 
TheString (L) 



New font flags 

Foreground color number 

X coord of upper-left corner 

V coord of upper-left corner 

Ptr lo the new pen mask 

New pen mode 

Ptr to new pen pattern 

Width of pen in pixels 

Height of pen in pixels 

Ptr to pen state record 

Ptr to new GrafPort 

Ptr to new port rectangle 

Scan line number (0-199) 

New SCB value 

Color # of background 
pattern 

Color # for pen pattern 

New textfacc word 

New text drawing mode 

Color number 

Pointer to pattern for color 

Width of string in pixels 

Ptr to text string 



Reference Section 215 





Function 


Stack 


Description of 


Function Name 


Numbei 


Parameters 


Parameter 


TextWidth 


SAB 


result (W) 


Width of text in pixels 






TheText (L) 


Ptr to start of text 






Count (W) 


Number of characters 



Table 1 


R6-2: QuickDraw II Error Codes 


$0401 


QuickDraw II has already been initialized. 


$0403 


QuickDraw II has" not been initialized. 


$0410 


Screen memory has been reserved. 


$0411 


The rectangle specified is invalid. 


$0420 


The pixel chunkiness is not equal. 


$0430 


The region is already open. 


$0431 


The region is not open. 


$0432 


The region has overflowed, 


$0433 


The region is full. 


$0440 


The polygon is already open. 


$0441 


The polygon is not open. 


$0442 


The polygon is too big. 


$0450 


Bad color tabic number. 


$0451 


Bad color number. 


$0452 


Bad sean line number. 



Table R6-3j The Major Functions in the Window Manager Tool Set ($0E) 





Function 


Stack 


Description of 


Function Name 


Number 


Parameters 


Parameter 


Begin Update 


$1E 


The Window (L) 


Ptr to window record 


Close Window 


$0B 


TheWindow (L) 


Ptr to window record 


DragWindow 


$1A 


Grid (W) 


Drag resolution (0= default) 






StartX (W) 


Starting X coord (global) 






StartY <W) 


Starting Y coord (global) 






Grace (W) 


Grace distance around bounds 






BoundsRect <L) 


Ptr to cursor boundary rect 






TheWindow (L) 


Ptr to window record 
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Function 


Stack 


Description of 


Function Name 


Number 


Parameters 


Parameter 


End Update 


$1F 


TheWindow (L) 


Ptr to window record 


FindWindow 


$17 


result (W) 


Location code for mouse-down 






Which Window (L) 


Ptr to space for window ptr 






PointX (W) 


X coord to check (global) 






PointY (W) 


Y coord to check (global) 


FrontWindow 


S15 


result (L) 


Ptr to window record 


Ge tCon ten t Draw 


848 


result i'L.i 


Ptr to update subroutine 






TheWindow (L) 


Ptr to window record 


GetContentOrigin 


$3E 


result (W) 


X coordinate of origin 






result (W) 


Y coordinate of origin 






TheWindow (L) 


Ptr to window record 


GetDataSize 


$40 


result (W) 


Data width 






result (W) 


Data height 






TheWindow (L) 


Ptr to window record 


GetDefProc 


$31 


result (L) 


Ptr to window def. subr. 






TheWindow (L) 


Ptr to window record 


GetFrameColor 


$10 


result (L) 


Ptr to color table 






TheWindow (L) 


Ptr to window record 


GetFullRect 


$37 


result (L) 








TheWindow (L) 


Ptr to window record 


GetlnfoDraw 


$4A 


result (L) 


Ptr to infobar drawing subr. 






TheWindow (L) 


Ptr to window record 


GetlnfoRefCon 


$35 


result (L) 


RefCon for infobar drawing 






TheWindow (L) 


Ptr to window record 


GetMaxGrow 


$42 


result (W) 


Maximum window width 






result (W) 


Maximum window height 






TheWindow (L) 


Ptr to window record 
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Function 


Stack 


Description of 


Function Name 


Number 


Parameters 


Parameter 


Get Page 


$46 


result (W) 


Horizontal distance (page) 






result (W) 


Vertical distance (page) 






TheWindow (L) 


Ptr to window record 


Gel Scroll 


$4*1 


resull iW) 


Horizontal distance dine) 






result (W) 


Vertical distance (line) 






TheWindow (L) 


Ptr to window record 


GetWFrame 


$2C 


result (W) 


Window frame hit vector 






The Window <L) 


Ptr to window record 


GetWRefCon 


$29 


result (L) 


Reference constant 






TheWindow (L) 


Ptr to window record 


GetWTitle 


$0E 


result (L) 


Ptr to title string 






TheWindow |Ll 


Ptr to window record 


GrowVV'indow 


SIB 


result (W) 


V w height 






result (W) 


New width 






\I in Width (W) 


Minimum width of content 






Max Width (W) 


Maximum width of content 






StartX (W) 


Starting X coord (global) 






Start Y (W) 


Starting Y coord (global) 






TheWindow (L) 


Ptr to window record 


Hide Window 


$12 


TheWindow (L) 


Ptr to window record 


Move Window 


$19 


NewX iWi 


X coord of upper-left corner 






NewY iWi 


Y coord of upper- It* ft corner 






J lie Window (L) 


Ptr to window record 


NewWiodow 


$09 


result (L) 


Ptr to window record 






Fa ram List (L) 


Ptr to window parameter tahle 


Refresh Desk top 


|39 


ClobRect (L) 


Ptr to redraw rectangle 


SeleclWindow 


SIJ 


TheWindow (L) 


Ptr to window record 
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Function 


Stack 


Description of 


Function Name 


Number 


Parameters' 


Ptmtmi iei 


SetContentDraw 


$49 


ContDraw (L) 


Window update procedure 






TheWindow (L) 


Fir to window record 


SetContentOrigin 


$3F 


xOrigin (W) 


X coordinate ot origin 






yOrigin (W) 


V coordinate of origin 






TheWindow (L) 


Ptr to window record 


SetDataSize 


$41 


dataWidth (W) 


Data width 






dataHeight (W) 


Data height 






TheWindow (L) 


Ptr to window record 


SetDefProc 


832 


DefProc(L) 


Window definition procedure 






TheWindow (L) 


Ptr to window record 


SetFrameColor 


$0F 


FrCoIorTbl (L) 


Ptr to new color table 






TheWindow (L) 


Ptr to window record 


SetFullRect 


$38 


FullRcct (L) 


Ptr to zoom rectangle 






TheWindow (L) 


Ptr to window record 


SetlnloDraw 


$16 


Info Draw (L) 


Information bur procedure 






TheWindow <L) 


Ptr to window- record 


SetlnfoRefCon 


$36 


InfoRefCon (L) 


Inlolnir reference constant 






TheWindow (L) 


Ptr to window record 


SetMaxGrow 


$43 


maxWidth (W) 


Maximum window width 






maxlioight (W) 


Maximum window height 






TheWindow (L) 


Ptr to window record 


Set Page 


•S47 


b?age(W) 


Horizontal distance (page) 






vPage (W) 


Vertical distance (page) 






TheWindow (L) 


Ptr to window record 


Set Scroll 


$45 


hScrotl (VV» 


Horizontal distance (line) 






vScroll W! 


Vertical distance (line) 






TheWindow (L) 


Ptr to window record 
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Function Name_ 
SetSysWindow 

SetWFrame 



SetWRefCon 
SetWTitle 

ShowWindow 
SizeWindow 



Function Stack 
Number Parameters 



Description of 

Parameter 



Start Drawing 
TaskM aster 



TrackGoAway 



TrackZoom 



$48 ThcWindow (L) 

S2D WFramc (W) 

ThcWindow (L) 
$28 WRefCon (L) 

TheWIndow (L) 
SOI'* TitlcPtr (L) 

ThcWindow (L) 
$13 ThcWindow (L) 

SI CI N ew Width (W) 

NewHeight (W) 
ThcWindow (L) 
S4D The Window (L) 

$1D result (W) 

EventMask (W) 
TaskReeord (L) 
$18 result (W) 

StartX (W) 
StartY (W) 
ThcWindow (L) 
$26 result (W) 

StartX (W) 
Start V (W) 
ThcWindow (L) 



Ptr to system window 
Window frame bit vector 
Ptr to window record 
New reference constant 
Ptr to window record 
Ptr to new title string 
Ptr to window record 
Ptr to window record 
New width of window 
New height of window 

Ptr to window record 

Ptr to window record 

Event code 

Event mask 

Ptr to task record 

Boolean: was goaway selected? 

X coordinate (global) 

V coordinate (global) 
Ptr to window record 
Boolean: was zoom selected? 
X coordinate (global) 

Y coordinate (global) 
Ptr to window record 
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Function Name 


Function 
Number 


Stack 

Parameters 


Description of 
Parameter 


Winds hut Down 


$03 


[no parameters] 




WindStartup 


$02 


UserlD (W) 


ID tag for memory allocation 


Zoom Window 


$27 


The Window (L) 


Ptr to window record 



Table R6—4: Window Manager Error Codes 



50E01 The first word in die NewWindow parameter list is not the correct 

table size. 
S0E02 The window record could not be allocated. 
$0EO3 Bits 14-31 in the TaskMask field of the task record are not zero. 



Table R6-5: Useful Functions 


in the Font Manager Tool Set ($1B) 


Function Name 


Function 
Number 


Stack 
Parameters 


Description of 
Parameter 


Choose Font 


$16 


result (L> 


ID for selected font 






currrntID (L) 


ID of current font 






fliin Specs (Wi 


Family specification 


Install Font 


SOE 


desired ID (L) 


Desired font ID 






scalcword (W) 


Scaling factor 


FM Shutdown 


$03 


[no parameters] 




FM Startup 


$02 


SysFontName 

(L) 


Ptr to system font name 






Isrrll) iWi 


ID lap for memory allocation 






DPAddr :\\ i 


Pointer to 1 page in bank 
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Function Name 


Function 
Number 


Stack 
Parameter?; 


Description of 
Parameter 


LoadS ysFont 




[no parameters] 




SetPurgeStat 


$0F 


fontID (L) 


ID for font to purge 






purge Stat (W) 


Purge status word 



Table R6— 6: Font Manager Error Codes 



$1B01 


The Font Manager has already been started up. 


$1B03 


The Font Manager is not active. 


$1B04 


The font family was not found. 


S1B05 


The font was not found. 


SIB06 


The font is not in memory. 


SIB07 


The system font cannot be made purgeable. 


S1B08 


Illegal family number. 


S1B09 


Illegal size. 


$IBOA 


Illegal name length. 


$IB0B 


FixFontMenu ha.s never been called. 
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Listing 6—1: How to Create and Display a Window 



DefineUlmd START 



PHfl 

PHA 

PushPtr TheWindow 

_NewW 1 ndow 

PopLong WindowPtr 

RTS 



; Window parameters: 



jSpace for result 
;Pointer to window record 
;Save pointer to window record 



TheWi ndow 


DC 


12'WindEnd-TheWi 


ndow 1 


Size of table 






DC 


I 'J61101110110100101 ' 


window frame type 






DC 


14'TheTiUe' 




Painter to window title 




DC 


14 a ■ 




ref con 






DC 


1 '40,4,182,608' 




zoom rec tang 1 e 






DC 


14'0' 




color table ( ■ 


default) 




DC 


i '0,0' 




document offset 






DC 


1 '1024,960' 




height ,width of c 


ata area 




DC 


M0,0' 




height, width max 


wi ndow 




DC 


M9.12' 




ver t , hor l z line 


movemen t 




DC 


I '144 ,592' 




vert , hor l z page 


movement 




DC 


[4*0' 




info bar refcon 






DC 


I2M2' 




info bar hei gh t 






DC 


1 4 ' ' 




frame defproc (0 


= standa 




DC 


I4'Do! nfoBar ' 




info bar defproc 






DC 


14'WindUpdate' 




content defproc 






DC 


I '40,4 ,182,608' 




Content region rectangle 




DC 


I 4 ■ - 1 ' 




At the front 






DC 


I 4 • ' 




Storage (use MM) 




WlndEnd 


ANOP 










TheTitle 


DC 


11 'A GS Window' 


;Window title 




WindowPtr 


OS 


* 


i Poi nter 


to window 





END 



; TaskMaater calls this routine whenever an update 
; event occurs. It La responsible for redrawing the 
; contents of the window. 
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WindUpdate START 

; (lake the data bank equal the code bank so you 
; can use absolute addressing: 

PHB 
PHK 
PLB i data bank » code bank 

; [insert window drawing code here] 

PLB 

RTL ;Do not use RTSli 

END 

Taskmaster calls this routine when xt needs to 
draw the interior of the information bar. 

; See explanation in listing 6-2. 

DoInfoBsr START 

; [insert drawing code here! 

; Remove 12 bytes of input parameters from the stack: 

; Move return address 

; up by three long words 



;Rai5e stack pointer by 
; three long words. 



END 

Listing 6-2: A Procedure tor Drawing an Information Bar 

This is an information bar drawing procedure- It centers a 
text string pointed to by the infobar refcon in the bar. 

TaskMaster calls InfoProc by pushing three long words on the 
stack (pointer to infobar rectangle, the information bar refcon, 
and a pointer to the window record), then performing a JSL . 



LDA 


2,S 


STA 


14,5 


LDA 


1 ,S 


STA 


13, S 


CLC 




TSC 




ADC 


*M2 


TCS 




RTL 
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; On exit, these parameters must be removed by moving the 
; return address (end stack pointer) up by 12 bytes. 

; Note: top, left, bottom, right are defined in Standard . Asm. 

InfoProc START 



1 These are the direct page addresses after aligning the new 
1 direct page with the stack; 



Old.DP EQU 

01d_DB EQU 

ReturnAddr EQU 

IB.WindPtr EQU 

IB^RefCon EQU 

IB.RectPtr EQU 

PHD 
PHB 

PHK 
PLB 

TSC 
TCD 

LDV 

LDA 
STA 

LDY 

LDA 
SEC 

SBC 
PHA 



$01 

0ld_DP+1 

QLdlDB+2 

ReturnAddr+3 
IB_WindPtr*4 
IB_RefCon*4 



"left 

[ IB.RectPtr] ,Y 

IB_Temp 

*r lgh t 
[IB.RectPtr] ,Y 

lB_Temp 



Old direct page 

Old data bank 

JSL return address 

Pointer to window 

Reference constant (string pointer) 

Pointer to infobar rectangle 

;Save direct page 

•.Save data bank register 

•,5et data bank = code bank so we 
; can use absolute addressing 



-, Align new d. p. with stack 
;Get left edge 

; Get right edge 

;CalcuJate width of rectangle 



PHA 

PushLong IB_RefCon 

_StrmgWidth 

PLA 

ST A IBJTejnp 

PLA 



CMP 
BCS 

LDA 
BRA 



IB_Temp 
Ge t Margi n 

Ge t Margi nl 



; Room for result 
'.Pointer to text string 

; Th i 5 i5 the width of the text 



;Get width of rectangle 

;Wider than text? 
; V e s , so branch 

; Flush with left side 
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Getmargin SEC 

SBC IB_Temp ;Calculate remaining space in reel 

LSR ft 'Divide by 2 to get left margin 

GetMarginl STA IB_Ternp 

LDY 'left 

LDA [IB_RectPtr J ,Y ; Add margin to left edge position 

ADC IB_Temp 

PHA ; X-coordi nate for floveTo 

LDY 'bottom 

LDA [IB_RectPtr3 T Y ;Get bottom edge 

SEC 

SBC *2 ;(room for descenders) 

PHA ; Y-coordi nate for MoveTo 

_MoveTo ^Position the drawing pen 

PushLong IB.RefCon ;Push refcon pointer 

_Draw5tring ;Draw string pointed to by refcon 

PLB ;Restore data bank register 

PLD ■, Restore direct page 

; Remove parameters from stack before leaving. This as done 
\ by moving the 3-byte return address, and the stack pointer, 
; up by the size of the parameters, then ending with RTL. 

■, Move return address 

1 up by three long words 



;Raise stack pointer by 
j three long words. 



RTL S {called with JSL) 

IB.Temp DS 2 

END 
Listing 6-3: How To Define an STR Macro 



LDA 


2,5 


STA 


14, S 


LDA 


1,S 


STA 


13, S 


CLC 




TSC 




ADC 


'12 


TCS 





MACRO 
ilab STR itext 

tlab DC I1'L:*teit« ;Length byte 

DC C'Atext" ;ASCII characters 
MEND 
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Listing 6-4: Using StringWidth To Center a Line of Text 



; Enter this subroutine with a line number in Y. 

; The pointer to the text string must be in A (hiqh) and X (low). 

left GEQU 2 
right GEQU 6 

Center It START 

STY LinePos -,Save vertical 

; Calculate width of string: 

PHA S space for result 

PHA ;push pointer (high) 

PHX '.push pointer (low) 

_St r ingWidth 
PopWord TextWidth 

^Calculate width of content region: 

PushPtr PortRect 

_GetPortRect ;Get content rectangle 

SEC 

I da PortRectTight ;Right side minus 

SBC Por tRectMef t ; the left side. 

jLeft margin is 1 /2» (WindowWidth-TextWldth ) from left of PortRect: 

5BC TextWidth 

LSR A ;Divide by 2 

CLC 

ADC PortRect* left ;Add to left side 

PHA -Horizontal position 

PushWord LinePos -.Vertical position 

_Mo\/eTo 

PushPtr TheText 

_DrawStnng ;Draw the string 

RTS 
LinePos DS 2 -.Vertical line position 
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PDPtRect DS 8 -.Content rectangle 

TextWidth DS 2 
END 

Listing 6-5: A Subroutine for Displaying Text in All Sixteen Colors 

Use this subroutine in 320x200 mode so that you see all 
16 colors. (Do this by setting VidMode to tOO and 
XMaxClamp to 320 in Standard . Asm. ) 

TextColor START 

PushWord *3 

LDA #10 

STA VertPos 

PHA 

_MoveTo i Posit ion on first line 

; Just for fun, draw the text in boldface: 

PushWord #100000001 ;Set the bold bit 
_5et TextFace 

LDX #0 -,Start with color #0 

ColorText PHX 

PHX 

_SetForeCo lor ;Set foreground color 

PushPtr TheText 

_DrawString jPrint the text 



; Move to next line: 



PushWor 


d #3 


CLC 




LDA 


VertPos 


ADC 


#9 


STA 


VertPos 


PHA 




_MoveTo 




PLX 




INK 




CPX 


#16 


BNE 


ColorText 



; 1 ef t side 

; (height of 1 ine) 
\ 1 l ne number 



■ t At last color yet? 
;No, so branch 



RTS 
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VertPos D5 2 

TheText STR 'The quick brown fox jumped. 1 

END 

Listing 6-6: How To Define and Use a QuickDraw Polygon 
DefinePoly START 

; First move the pen to the desired position; 

PushWord #100 -.horizontal 

PushWord #120 -.vertical 

JMaveTo 

; ... then open the polygon record: 

PHA ;space for result (handle) 

PHA 

^QpenPo 1 y 

PopLong PolyHndl iPap the polygon handle 

; ... then draw the outline of the polygon with Line or LineTo 
; (this defines a pentagon): 

PushWord #50 

PushWord #0 
_L l ne 

PushWord '25 

PushWord '-25 
_L l ne 

PushWord #-50 

PushWord #-25 
_L i ne 

PushWord #-50 

PushWord #25 
_L i ne 

PushWord '25 

PushWord #25 
_Line 

» . . . then close the polygon record: 



_ClosePoly 
RTS 
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; To display the polygon, call ShowPoly: 
ShowPoly ENTRY 

PushLong PolyHndl 

_PaintPoly '<(° r Frame, Erase, Invert, Fill, 

RTS 
I To permanently dispose of the polygon, call ByePoly: 

ByePoly ENTRY 

PushLong PolyHndl 

_KillPoly 

RTS 

PolyHndl DS 4 yHandle to polygon record 

END 
Listing 6-7: The TextReader Program __^_ 



■ TextReader * 

• This program demonstrates how to deal + 

* with windows that have scroll bars, 

LIST DFF 
SYMBOL DFF 
ABSADDR ON 
INSTIME ON 
GEN ON 

KEEP WIND ;Dbject code file 

MCOPY WIND. MAC ; Macro file 

MyCode START 

5 Direct page global equates: 

TextHndl GEQU SO '.LONG 

TextPtr GEQU *4 ".LONG 

Using GlobalData 
Using Start Data 

JSR DoStartUp 
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i Define and display the menu bar: 

PushLang #0 
PushPtr MenuL2 

_NewMenu 

PushWord #0 
_ I riser tflenu 

PushLang #0 
PushPtr MenuLI 
_NewMenu 
PushWord #0 
_ Jnser tflenu 

PushWord '1 

_FixAppleP1enu ;Add DAs to Apple menu 

PHA 

_Fi xFlenuBar -.Adjust size of menu 

PLA 

_DrawMenuBar 

; Save the current direct page 

TDC 

STA MyDP 

_InitCursor ;Turn on arrow cursor 

; As Ic the user for the name of the file to open. To da this, 
I use the SFGetFile dialog box {see chapter 10): 

GetName PushWord #120 -, x 

PushWord #40 ■, y 

PushPtr SFPrompt '.prompt 

PushPtr FilterProc ^filter procedure 

PushLong #0 5 ( no file type list) 

PushPtr ReplyRec ;reply record 
_SFGetFile 

LDA good -,Get the result 

BNE Loadlt -.Branch if it was "open" 

JMP DoShutDown 

; Load a text file into memory. This is done using 
; ProDQS 16 commands (see chapter 10): 

Loadlt _QPEN DpenParms 
LDA refnum 
5TA refnuml 



Reference Section 231 



STA refnum2 

STA refnum3 

STA refnum4 

GETEOF EDFParm* 



PmhLi 


Ding #0 


PushL 


ong FileSize 


PushW 


o r d My 1 D 


PushW 


ord #18000 


PushL 


ong #0 


JHmwHi 


andl e 


PopLong TextHndl 


LDA 


[TextHndl ] 


STA 


TextPtr 


STA 


data_buf f 


LDY 


*2 


LDA 


[TextHndl] ,V 


STA 


TextPtr*2 


STA 


data_buff + 2 


LDA 


FileSize 


STA 


request 


LDA 


FileSize+2 


STA 


request *-2 



;space for result 
;Pu3h sue of file 

; Locked 

; (means nothing here) 

; Save handle to text area 
;de reference the handle 



_NEWLINE NLParms 

_READ ReadParms ;Read data in to TextPtr block 

_CLDSE CloseParms 

{Calculate size of document (in pixel lines). This is done by 
; multiplying the number of Carriage Returns by 9 (the height 
; of a 1 ine ) : 



;Get next character 

;End of line? 
;No, so branch 





STZ 


DocSi ze 




LDY 


#0 


GetSize 


LDA 


[TextPtr] ,Y 




AND 


#I7F 




CMP 


#I0D 




BNE 


Sk ip 1 nc 




CLC 






LDA 


DocSi ze 




ADC 


#9 




STA 


DocSi ze 


Sk i pine 


[NY 






CPY 


FileSize 




BNE 


GetSize 



;9 pixels per line 



s At end of f i le? 
;No, so branch 
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CLC 

LDA DocSize 

ADC f20 ^Provide a small bottom margin 

STA DocSize 



; Clip to max depth of 1 6K (14000) because of 
; QuickDraw boundary restrictions: 

CMP #i3FFF-9 ;Larger than max' 

BCC ShowWmd ;No, so branch 

LDA #*3FFF-9 ;Cllp to max (subtract 9 to avoic 

STA DocSize ; adverse effects on last line) 

; Define and display the window: 

ShowWind PHA '.Space for result 

PHA 

PushPtr MainWindow ;Pointer to window record 

_NewUindow 

PopLong WindowPtr jSave pointer to window record 

*, Change the title of the window to the name of the file! 

SetTttle PushPtr Filename 

PushLong WindowPtr 
SetWTitle 



;A11 events 

; Ge t result code 

■ T Menu item selected? 
; Yes , so branch 



CMP 'wlnGoAway ;ln close box? 

BNE EvtLoop ; Ignore everything else 



PushLong TextHndl 

.DisposeHandle -,Free up text block 

PushLong WindowPtr 

_CloseWindow ^Delete the window 

BRL GetName ',Go get another file 
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Evl Loop 


PHA 

PushWord #1FFFF 

PuihPtr EventRec 

_Tasknas ter 

PLA 




CMP 
BEQ 


*w I nMenuBa r 

DoMenu 



; Handle menu selections: 



DoMenu 


LDA 


TaskData 




AND 


*$Q0fF 




A5L 


A 




TAX 






JMP 


( Menu Tab 1 e , 


MenuTabie 


DC 


I 'DoAbout I » 




DC 


I 'DoQuitl f 


DoAbout 1 


JSR 


FixMTi t le 




BRL 


Evt Loop 


DoQuitl 


JSR 


FixMTitle 




JMP 


DoShu tDown 



;Convert to base 

1x2 to step into table 

;Call menu item handler 



FixMTitle PushWord *False 

PushWord TaskData*2 

_Bi 1 i teMenu 

RTS 



•„ Highlighting off 
;Get menu ID 



END 



TaskMaater calls this routine whenever an update 
event occurs. It is responsible for redrawing the 
contents of the window. 



WindUpdate START 

Using ClobalData 

; Hake the data bank equal the code bank so we don't have 
; to use absolute long addressing: 



PUB 

PHK 
PLB 



;dala bank * code bank 



', Switch to the direct page the application uses so 
; that we can use TextPtr: 



PHD 
LDA 
TCD 



My DP 



• t Save current DP 
;5witch to our DP 



*, Get the current value of the PortRect. PortRect is 
; the rectangle describing the content region. 

PushPtr PortRect 
GetPortRect 
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• Seen for the first line In the document that will 
: appear in the window: 



;Coord of line *0 



LDA 


*8 


STA 


YPosition 


LDV 


*IFFFF 


PHY 





BRA FSQ 



Fi ndStar t 


LDA 
PHY 


[TeitPtrl ,Y 




AND 


#$7F 




CMP 


#*QD 




BNE 


FSt 




CLC 






LDA 


YPosit ion 




ADC 


#9 




STA 


YPo5i t i on 


FSQ 


LDA 


YPosition 




CMP 


Por tRec t *top 




BCS 


FS2 


FSt 


PLY 
INY 






CPY 


F i 1 eS i ze 




BNE 


Fi ndStar t 




PLD 






PLB 






RTL 




FS2 


PLY 
INY 

PHY 





;Get character 



; End of line' 
jNo, so branch 



;Add height of line 



;Get position in document 
;Past the top of PortRectV 
;Yes, so we're ready to start 



*,At end of file? 
; No , so bra nch 



; Move to 1st character of line 



PushWord #2 -.Move to left edge 

PushWord YPosition 

_MoveTo 

PLY 

; Determine the number of bytes in the line 

; so that we can draw them all at once with DrawText : 

NextLine STY StartPos 
STZ Counter 
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ShowL ine 


LDA 




[TextPtr] ,Y 




AND 




#S7F 




CMP 




**0D 




BEQ 




Go tL ine 




INC 




Counter 




INY 








CPY 




FileSize 




BNE 




ShowL 1 ne 




DEY 






Got Line 


PHY 








LDA 




Counter 




BEQ 




GotLi ne1 




CLC 








LDA 




StartPoa 




ADC 




TextPtr 




TAX 








LDA 




TextPtr+2 




ADC 




• 




PHA 








PHX 








PushW 


or 


d Counter 




_Draw 


r e 


xt 


Got L 1 ne1 


JSR 




CRLF 



;Get character 
;Strip high bit 
• F At end of line? 
;Yes, so branch 



;At end of file? 
;No, so branch 



;CR by itself 

;Yes, so don't draw anything 

{Push starting position 

; by adding offset to TextPtr 



; Number of bytes to draw 

;Move to next Line 
; Check to see if we've gone past the bottom of the window: 

Get current position 
Get buffer position back 

At end? 

Yes, so branch 

Get bottom of portRect 

go one line further 
Pen reached bottom yet? 
No, so branch 

PLD ;Restore DP 

Do not use RTS! I 



PushPtr 


PenPos 


_GetPen 




PLY 




INY 




CPY 


FileSize 


BEQ 


Exit 


LDA 


PortRect 


CLC 




ADC 


#9 


CMP 


PenPos+v 


BCS 


NextLine 


PLD 




PLB 




RTL 
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PortReet 


D5 


B 


Star tPos 


DS 


2 


Counter 


DS 


2 



; rectangle 



END 



* This is the filter procedure for SFGetFile. * 

• It is explained in chapter 10. * 
•••■■• •••f«««»t*« *•»»*•*■#•*•*•»«* ••*•*•••••■•■ 

FilterProc START 





PHD 






TSC 






TCD 






LDV 


#16 




LDA 


t$6J T V 




AND 


#*00FF 




CMP 


**B0 




BEQ 


FPO 




CMP 


M04 




BEQ 


FPO 




LDA 


*1 




BRA 


FP1 


FPQ 


LDA 


#2 


FP1 


PLD 






5TA 


8 ,S 




LDA 


2,S 




STA 


6,S 




LDA 


i t s 




STA 


S,S 




TSC 






CLC 






ADC 


*4 




TCS 






RTL 





;Save direct page 

; Align d.p. with stack 

■.Offset to file type code 

;(use low byte only) 
■, SRC file? 
;Ves, so branch 
;TXT f l le? 
;Yes, so branch 

;1 ■ display/not selectable 

\2 ■ display/selectable 

-.Restore d.p. 
;Saue the result 

?Move 3-byte return 

; address up by 4 bytes. 



;Add 4 to the 
; stack pa int er . 



END 

» Move cursor to left side of next line: 

CRLF START 

Using GlobalData 
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PushPtr PenPos 
_GetPen 

PushWord *2 

CLC 

IDA PenPos+v 

ADC #9 

PHA 

_MoveTo 

RTS 

END 

COPY STANDARD. ASH 



;Get current pen position 

; lef t edge 

;9 is the height of the system font 
; New vertical position 



■,5tandard startup/shutdown 



GlobalData DATA 

-, Window parameters: 

HindowPtr DS 4 



MyTi tie 


DC 


11 »0< -,Nu 


Ma 1 nWi ndow 


DC 


12'WindEnd-MainWindo 




DC 


I *X1 101 1 101 1 01001 01 ' 




DC 


H 'MyTitle 1 




DC 


14'0' 




DC 


1 '40,4,182,608' 




DC 


1 4 ' * 




DC 


I ' , ' 


DocSi ze 


DC 


I '1024,960' 




DC 


1 '0,0' 




DC 


l'9,12' 


Page Jumps 


DC 


I ' 144 ,592' 




DC 


14' i 




DC 


I2M2' 




DC 


14 ■ ' 




DC 


14'0« 




DC 


14'NindUpdate" 




DC 


1 MO ,4, 182,608' 




DC 


J4I-1 i 




DC 


14 ■ ' 


WindEnd 


A NOP 





;Pointer to window 

■, Null name-, filled in later 
S l ze of tab 1 e 
window frame type 
Pointer to window title 
r ef con 

zoom rec tang 1 e 
color table (0 ■ default) 
document offset 
height, width of data area 
height, width max window 
vert, horiz line movement 
vert, horiz page movement 
info bar refcon 
info bar height 
frame defproc (0 
info bar defproc 
content defproc 
Content region rectangle 
Ai the front 
Storage (use flM) 



■ standar 



j Menu/item lists: 
flenuLI 



MenuL2 



DC 

DC 

DC 

DC 
DC 



C> §VN1X ' .rl'OD' ;Apple menu 
C'**About this program ♦ . - YN256V ' , H ' QD' 

£*> File \N2',H f 0D' ;File menu 

C'QuitNNasy'Qq' ,H'0D' 

C .' ;End of menu 
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My DP DS 2 
YPosition DS 2 
PenPos DS 4 



tlication's direct page 
•Current pen position 



j SFGetFile data: 



SFPrompt STR 



■Select a file to view: 



ReplyRec 

good 

f i letype 

auxtype 

F l 1 eName 

fullpath 



ANOP 

DS 

DS 

DS 

DS 

DS 



z 

2 

Z 

16 

129 



'.Non-zero if open pressed 
-.ProDDS file type 
;ProD0S auxiliary file type 
; Name of file in prefix 0/ 

*, Full pathname 



; Data for file l/D operations: 

OpenParms ANQP 

refnum DS 2 

DC M'FileNarne' 

DS 4 

EOFParms ANOP 

ref numl DS 2 

FileSize DS 4 



KLParms ANQP 

refnum2 DS 2 

DC I 2 • ' 

DS 2 



' t di9able newline read mode 



ReadParms ANOP 

refnum3 DS 2 

data. buff DS 4 

request DS 4 

DS 4 



^Pointer to data area 



CloseParms ANQP 
refnum4 DS 2 

;Event Record for TaskNaater: 



FventRec ANDP 
What DS 2 

Message DS 4 



; Event cade 
:Event result 
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When 


DS 


Wher* e 


DS 


Modifiers 


DS 


TaskData 


DS 


Task Mask 


DC 




END 



4 ; Ticks since startup 

4 ;Mouse location (global) 

2 ^Status of modifier keys 

4 ;TaskMaster data 

H'SOOOOIFFF' ;TaskMaster handles all 
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CHAPTER 7 



Using Pull-down 
Menus 



One of the difficult decisions a programmer faces when developing an application 
is how bo design the command interface between the user and the application. One 
school of thought says a user should be Forced to memorize command names which 
must be typed in from the keyboard. The advantage of this common technique is 
that once the commands are mastered, they can be entered very quickly, The two 
main disadvantages are that it can take a long time to memorize the commands and 
that commands are easily forgotten if a program is not used for a while. 

The other extreme is to insist that the user must always select a command from 
a displayed list of possible choices. Such a list is called a menu. This technique is 
popular with users who are just learning how to use a program, because all the 
commands are immediately obvious. The disadvantage is it becomes tedious to call 
up and hunt through a menu once you have mastered the program and know exactly 
what you want to do. 

II you follow Apples standard user-interface guidelines, you will implement the 
menu technique with GS applications that use the super high-resolution desktop. 
To define menus and handle menu activity in standard ways, use the Menu Manager 
tool set {tool set 15). 

Despite its name, the Menu Manager does make concessions to the couunand- 
d riven interface because you can quickly select certain menu items by pressing a 
character key while holding clown the Open-Apple (Command) key. Such a key is 
called a keyboard equivalent. 

The mm ich menu defined by a GS application that uses the Menu Manager 

appear in a rectangular menu htir across the top of the graphics screen (see figure 
7—1), A user can see the contents of a particular menu by moving the mouse cursor 
over that menu's title and holding down the mouse button. This causes a rectangle 
containing the names of all the items in the menu to appear below the menu's title. 
(Because the effect Is like pulling down a window blind, a cs menu is called a pull- 
down menu.) The items are stacked vertically. 
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Figure T— 1: An Apple IIc;s Menu Bar and a Pull-down Menu 



A Fill 



Undo <5Z 



Cut 6X 
Copy ciC 



Paste tiV 



%\ 



Once the menu has been pulled down, a user tan select an item by moving the 
mouse down or up to highlight the appropriate item name and then releasing the 
mouse button. The user can also inspect an adjacent menu by moving the mouse 
(with the button still down) to the left or right while it is in the menu bar area. 

Tliis chapter covers implementing pulldown menus in cs applications, creating 
and displaying menu bars, and controlling the appearance of individual items inside 
menus. 

STARTING UP AND SHUTTING DOWN THE MENU MANAGER 

Just as with any tool set T the start-up function must be called before the Menu 
Manager can be used. The function name is MenuStartup. Before calling Menu- 
Startup, however, you must start up QuickDraw, the Event Manager, and the 
Window Manager — the Menu Manager uses these tool sets to perform some of its 
functions. 

Here is how to start up the Menu Manager: 



PushWord MylD 
PushWord DPAddr 
_ftenuS tar tup 



;Program ID (from MMStartup) 
jress of direct page area 



DPAddr points to a one-page area in hank zero of memory that the Menu Manager 
uses for direct page storage 1 . Use NewHandle to allocate this space. 

MenuStartup perforins all the housekeeping needed to gel the Menu Manager 
up and running, This function creates an empty system menu bar T makes it the 
current menu ban and displays it at the top of the screen. 
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just before your program ends, call Menu Shut Down to free up the memory areas 
used by the Menu Manager. It requires no parameters and returns no results on 
the stack. 



CREATING A MEM 



To create a menu, use the New Menu function. It requires only one parameter — a 
pointer to a menu/item line list — and returns a handle to the menu record: 



PHA 

PHfl 

PushPtr PfenuList 

_NewMenu 

PopLong MenuHndl 



;space for result (long) 
iPointer to menu/item list 
;Pop handle to the menu 



Make sure you save the handle returned by NewMenu because you will need it 
when you add the menu to the menu bar with InsertMenu. Note that if the handle 
is 0, the menu could not be allocated, either because there is no memory available 
or because the menu/item line list is invalid. 

The menu/item line list is a series of lines, each followed by a null (ASCIJ $00) 
or a carnage return (ASCII $0D). A typical list looks something like this, in assembly 
language format: 

TheMenu DC C'» Edit \N3',I1 r Q» 

DC C'##Undo\N2S6V« r 1 1 " T 

DC C , ##Cut\N£57' , II '0' 

DC C«##Copy\N258' ,11 '0' 

DC C'##Delete\N2S9« ,11 ' » 

DC C . ■ 

The first line in the list defines the title for the menu; the first character (» informs 
NewMenu that this is a menu title, not an item name. It is followed by another > 
character, which simply acts as a place holder for the length of the string. (The 
Menu Manager fills in the length when you call NewMenu.) The menu title itself 
comes next, terminated by a backslash and some special characters defining the ID 
number for the menu. More information about these special characters is given 
below. 

Notice that there is one space to the left and one to the right of the title name. 
This is not required, but it provides aesthetic gaps between adjacent menu titles in 
the menu bar. 

Subsequent lines define menu items in the order in which they are to appear in 
the menu. Each line begins with an item character (#) that must be different from 
the menu title character. Following it are a dummy place holder character, the 
name of the item, and a terminating backslash followed by special characters. 



Creating a Menu 243 



The list is terminated by a character (.) that is different from the menu item 
character but could be the same as the menu title character. In fact, if you are 
defining several menu/item lists in sequence, the menu title character for the next 
list can be used as a terminator for the current list. Just be sure to follow the last 
list with a terminator character. 

By the way, there is nothing magical in the three characters used in this example 
Any characters may be used, as long as the menu item character is different from 
the menu title character and the terminator character is different from the menu 
item character. 

Following each title and item name in the list is a backslash character (\), The 
backslash signifies the end of the menu or item name and the beginning of a series 
of special characters. In the example, the special characters arc of the form "Nxxx" 
where "xxx" represents a decimal ID number for the title or item. Other special 
characters you can use are summarized in table 7-L Most of them affect the 
appearance of the text in the line. 

The program in listing 7—1 shows how to create three standard types oi menus: 
an Apple menu, a File menu, ami an Edit menu, each using Menu Manager 
functions, 

ID Numbers 

Every menu title name must be associated with an ID number from I to 65535. 
None of these numbers are reserved, but each menu title must have a unique 
number 

The range of ID cumbers permitted lor item names is narrower. The numbers 
from 1 to 249 are reserved for use by desk accessory items The numbers from 250 
to 235 are reserved for special editing items and a Close item, which are often 
needed by desk accessories: 

Cancel last editing operation 
Cut selected text, put it on the clipboard 
Copy selected text to the clipboard 
Transfer text from the clipboard to the document 
Cut selected text; do not put it on the cliphoard 
Close 255 Close the active window 

(The clipboard is a data area maintained by the Scrap Manager It facilitates the 
movement of data within an application or from one application to another.) 

The first five items should be placed in a menu called Edit. The Close item 
should be placed in a menu called File. 
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Undo 


250 


Cut 


251 


Copy 


252 


Paste 


253 


Clear 


254 



Table 7-1; 


Special Characters for 


Menu/Item Lists 


Special 
Character 








Meaning 


\ 








Beginning of special characters 


• 








Keyboard equivalent characters follow 
(primary followed by alternate) 


B 








Boldface the name 


c 








Mark character follows 


D 








Disable (dim) the name 


H 








Two-bytt binary ID number follows 
{$0001 to $FFFF, low-order byte 

first) 


I 








Italicize the name 


N 








Decimal ID number follows (1 to 65535) 


U 








Underline the name 


V 








Put a dividing line under the name 
(but do not use a separate item) 


X 








olor-replace highlighting 


NOTE; All tlii'se 
titles. 


special ( 


har* ters 


inuv bf used with (tern names, t'sf only \, D. II, N. mid X with menu 



When these ID numbers are assigned to these items, and a TaskMaster evenl 
loop is used, the special Items will automatically be passed to an active desk accessory 
for processing. See chapter 9 for more information on desk accessories 

The rest of the ID numbers, from 25H to 65535, may be used by the application 
in any way it sees fit. Keep in mind, however, that each menu item must have a 
unique ID number, although permanently disabled items maj share the same ID 
number. 

When you art 1 defining a series of menus, you might want to number the items 
consecutive! 1 , from 256. This makes it possible to access the subroutine to be called 
when the item is selected by doubling the low-order byte of the item number and 
using the result as an index into a table of two-byte subroutine addresses. The 
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standard Edit, File, and Desk Accessory items, which have numbers below 256, 
would be treated as special cases. 

Here is a code fragment thai illustrates this technique: 

; Enter here with the menu item number in A; 

CP1P #256 ^Standard Edit, Close, or DA? 

BCC DoSpecial ;Yes, sa branch 

AND #tQQFF «, Isolate low-order byte 

ASL A ;Double to get index into table 

TAX 

JMP (ITEN.TBL.X) ;Pass control to item handler 

DoSpecial NDP -,Handle special cases here 

RTS 

ITEP1_TBL DC 12'Dol tem2SG' ;Addreas of item #256 handler 

DC 12 T Dol tem2S7' -.Address of item #257 handler 

DC 12 r DoItem258' -.Address of item #258 handler 

You can use the H special character to specify the item or menu number in binary, 
rather than decimal, form. If you use the II. follow it with the two-byte binary 
number, low-order byte first. For example, to assign an item number of $0103. 
ify an item line of the form: 

DC C'##The Item\H»,h"03 01 ' , 1 1 ■ D ■ 
You could also use I2'§0T03' instead of H'03 01\ 

The Appearance of an Item 

Several special characters, ran be used to affect the appearance of an item in a menu. 
The program in listing 7-2 indicates how to use them. 

Three special characters are available for selecting the typeface oi an item name: 
B (boldfaced), I (italicized), and I 1 (underlined). For example, to attach all three 
laces 1° an item with an ID or 323, put the Following line in the menu/item line list: 

DC C*##My Ftem\N323BIU» ,11 •O* 

Note, however, that the standard system font used by the c;s cannot be underlined. 
Furthermore, current versions of QuickDraw do not support italics. 

To disable an item, use the special character D, A disabled item is dimmed in 
the menu and cannot be selected when the user pulls down the menu. You should 
disable an item whenever the action associated with it is not appropriate in the 
current environment. For example, if you have an item called Open Window, and 
the window is already open, you should disable the item. 
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Dividing lines, used to separate groups of related items in a menu, should always 
be disabled. Here is how to define a disabled dividing line iu a menu/item line list: 

DC C'##-VN324D' , 11 '0' 

The Menu Manager interprets a single hyphen as a row of hyphens extending across 
the width of the menu. 

You can also create a dividing line with the V special character. This type of 
dividing line is really just an underline and so does not use up the space of an entire 
item, The main advantage of using it instead of a true dividing line- is that you can 
fit more menu items in a menu. 

The X special character denotes a special form of highlighting to be used when 
a menu title or a menu item is selected. The- default highlighting method is called 
XOR, which causes a name to be inverted When an X special character is specified, 
color-replace highlighting is used instead of the XOR method; thi> method causes 
only the white background ol a colored object to be inverted. 

You will use color-replace highlighting for a menu whose title is the colored Apple 
logo. By convention, this menu appears on the left side of a menu bar and contains 
the names of all the active desk accessories in the system and an "About... item 
that displays information about the program. To define the title for the standard 
Apple menu, use the following line; 

DC C>>fa\N1 X « , [ 1 • • 

The Menu Manager substitutes the colored Apple logo for the (u character, as long 
as there are no additional spaces on either side of the menu title character (<§ 

Keyboard Equivalents 

As you will see later in this chapter, a user may select some menu items by pressing 
a character key while holding down the Open-Apple modifier key. Use the * special 
character to assign two keyboard equivalents to a menu item. The two characters 
immediately following the * are the primary and alternate keyboard equivalents. 
The primary character is shown to the right of the item name when the menu is 
pulled down. 

If the primary keyboard equivalent is an alphabetic character, it should be in 
upper case. The alternate equivalent should then be set to the corresponding lower- 
case character. Here are some examples: 

DC C'##Cut\N256»Xx * , M '0' 
DC C'##Help\N3Q3*7/' , 11 '0» 

Notice the two standard keyboard equivalents for a help item. The primary character 
is ? and the alternate is f. Because these two characters are associated with the same 
key. help will arrive, notwithstanding the status ol the Shiit key. 
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Marking Items 

The final special character is C. It is used to mark an item by placing a special 
character to Ihe left of its name in a menu. By convention, an item is to be marked 
only if a feature associated with it is active, or on. For instance, if you have a menu 
of font sizes, the one that is currently active should be marked and the others 
unmarked. 

Here is an item line defining an item marked with the character x: 

DC C'##Underline\,N322Cx l ,It '0' 

A more common mark character is the checkmark {ASCII 18), but you cannot put 
it directly into item lines because it is not a standard keyboard character. Once the 
menu has been defined, you can set (he mark character to a checkmark with the 
CheckMItem function (see the section below on "Checking and Marking"). 

CREATING THE MENU BAR 

Once you have defined a series of menus with New Menu, you are ready to add 
them to the system menu bar. To do this, use the InscrtMenii function: 

PushLong MenuHndl ;Handle to menu to be inserted 

Pu^hUlord #0 ; Insert at left side of menu bar 

_ J nser tlfenu 

The second parameter passed to Insert Menu is the ID of (he menu after which the 
menu whose handle is MenuHndl is to be inserted. If the number is 0, as in the 
example, the menu is inserted before the first menu in the menu bar. The easiest 
way to add a group of menus to the menu bar is tu insert them in order from right 
to left, using a ID parameter each time. 

If your menu bar includes an Apple menu, defined by a >>f«\NTX line in the 
menu/item line list, you should add the names of all the active desk accessories to 
it, at least if the applications plans to supporl accessories. Do this using the Fix- 
AppleMenu function: 

PushWord #1 ;Menu ID 

_F lxAppl eMenu 

The parameter passed to FixAppleMenu is the ID number of the menu to which 
the names of the desk accessory items are added. The desk accessories are given a 
consecutive set of ID numbers, beginning with 1. ID numbers from 1 to 249 are 
reserved for use by desk accessories; when TasleMaster determines that you have 
selected a desk accessory item, it automatically opens the desk accessory for you. 
See chapter 9 for more on desk accessories. 

Once all the menus have been added to the bar you must call PixMenuBar to 
permit the Menu Manager to calculate the height of the menu bar and menus and 
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the maximum width of each menu. The Menu Manager needs this information so 
that it can draw the menu bar properly. FixMenuBar returns a parameter, the height 
of the menu bar, so you call it as follows; 

PHA ;space for result 

_F lxttenuBar 

PLfl ; pop height of menu bar 

The application probably will not need to know the height of the menu har r so you 
can discard the result. You must call FixMenuBar every time you change an item 
name or menu title so that the Menu Manager can adjust its internal record of the 
menu dimensions accordingly. 

You are now ready to display the menu bar on the screen. For this, use 
DrawMenuBar — it requires no parameters, 

The program in listing 7-1 above illustrates how to create and display a menu 

bar. 

Changing the Name of a Menu 

If you wish to change the name of a menu after it has been defined, use Set- 
MenuTitle: 

Pu5hPtr NewTitle (pointer to name string 

PushWord #258 ;Menu ID code 

_SetMenuTi t le 

NewTitle STR 'ANewTitle 1 

NewTitle is a string that is preceded by a length byte. Call DrawMenuBar to redraw 
the menu bar after changing the name of a title, 

CHANCING ITEM ATTRIBUTES 

An explanation of how to use special characters in the menu/item line list to set the 
initial appearance of a menu item was given earlier in this chapter. You can also 
change an item's appearance, or its name, after the menu has been created, using 
several Menu Manager functions. Those functions are the subject of this section. 

Changing the Name 

To change the? name of an item, use Set M Item or SetMItemName. SetMItem 
requires two parameters, a pointer to the new item line and the ID oi the item to 
be renamed: 
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PushPtr NewLine 
PushWord #256 
_SetMl tem 
RTS 



^Pointer to new item line 
;item ID 



NewLine DC C ' ##A Different Name • , 1 1 ' ' 

The- first two characters in the string for the new name t## in the example) are 
always ignored, as arc any characters following a V character, and the \ character 
itself. Thus, the new item name will have the same Special attributes as the one il 
is replacing. 

You can also use SetMItemName to change the name oj an item: 



PushPtr NewNome 
PushWord #256 
_Se tM 1 t emName 
RTS 



; Pa inter to new strinc 
; item ID 



NewName STR 'ft Different Name' 

In tins case the first parameter i> a pointer to a standard string. All other item 
attributes, such as text style and keyboard equivalents, remain unchanged. 

When you change the name oi an item in a menu, the width of the menu may 
change. As a result, you must call CalcMenuSize to permit the Menu Manager to 

recalculate the width: 

PushWord #0 ;G means: calculate default width 

PushWord #0 *, means: calculate default height 

PushWord #256 ;thia is the menu ID 
_Calcf1enuSi ze 

[f you do not call CalcMenuSize, and the new item name is too long, some of it will 
"spill off' into the background when you pull down the menu. 

Enabling and Disabling 

As mentioned earlier in this chapter, an item can be disabled or enabled. A disabled 
item is one thai is not selectable; it appears dimmed in the menu. An enabled item 
can be selected and appears in normal script. 

You should disable items that are not relevant to the activity currently in progress. 
If you do so, the user cannot waste time selecting a meaningless activity lo perform. 

Here is how to disable an item; 



PushWord #266 
_Di sableMI tem 



\ I tem ID number 
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The corresponding enable function works similarly; 

PushWord #266 ; Item ID number 

_EnableMI tern 



Inserting and Deleting 

To insert an item into an already-defined menu, use InsertMItem. It requires three 
parameters: a pointer to an item line defining the menu item, the ID of the item 
after which the item is to be inserted, and the ID of the menu to which the item 
is to be added. Here is how to call InsertMItem; 

PuahPtr ItemEntry ;Pomter to item line 

PushWord #257 ;Item number to add after 

PushWord #3 ;Menu number to add to 

_ I nser t MI tern 
RTS 

ItemEntry DC C'##Inserted I tem\N333' , 1 1 ' ' 

It you specify an item number of 0. the item will be inserted at the top of the menu, 
An item number of IFFFF causes the item to be added to the end of the menu. If 
the menu number is 0, the first menu is selected. 

The new item definition pointed to by InsertMItem *s first parameter has the 
same format as an entry in a menu/item line list. Ft must be followed by a null 
chaiMetei :() or a return character (13). 

You can also delete items from a menu. For this, use DeletoMIn rn 

PushWord #343 ; ID of item to be deleted 

_Del et eM I tern 

Vim should not ust- DeleteMItem as a substitute for DisableMItem. 

After you have used the InsertMItem or DeleteMItem functions, the vertical 
si/c of the menu necessarily will have changed, so call CalcMenuSize as you won Id 
after using SetMltem to change an item name. 

Cheeking and Marking 

You can check or micheck a menu item using the CheckMItem function; 

True GEQU $8000 

PushWord #True ;True = check it 

PushWord #277 ; i tern ID number 

CheclrMI tern 
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The first parameter pushed on the stack is a Boolean instruction indicating whether 
a check mark (ASCII code 18) is to appear to the left of the item name (true) or 
whether it should not appear (false). This example checks item 277 because the 
Boolean parameter is true. Push a value of if you want to uncheek the item. 

You can place any character you like to the left of the item name using the 
SetMItemMark function. Here is how to use a diamond character as the marking 
character: 



PushWord #f!3 ;ASCII code for "diamond" 

PushWord #333 ;item ID number 

.SetMftemMark 



Here are the codes for the four special icons included in the system font: 



17 open-apple icon 

18 checkmark icon 

19 diamond icon 

20 solid-apple icon 



If you want to remove the marking character, specify an ASCII code of for the 
marking character. To determine which character is currently marking an item, use 
GetMItemMark: 



PushWord #0 ;space for result 

PushWord #333 ;item ID number 

_GetMI t tmMar k 

PLA ;Reault contains character code 



If the item specified is not marked, the result is 0. 



Changing the Text Style 

Item names can be drawn in plain text or they can be boldfaced, italicized, under- 
lined, outlined, or shadowed. Select a text style by passing a style word to Set- 
MltemStyle as follows: 

PushWord #X00OGG0Q1 ;style word (bold) 

PushWord #257 ; item ID number 

_SetMItemStyle 
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Five bits in the style word enable the five fundamental style attributes: 



bitO 


bold 


bit L 


italic 


bit 2 


underline 


bit 3 


outline 


bit 4 


shadow 


bit 5-15 


zero 



To select a particular style, set the appropriate bit to 1 The style types are not 
mutually exclusive, so you can combine them as you like. Use a style word of if 
you want the item name drawn in plain text. 

• Note: Early versions of QuickDraw do not support italic, outline, or shadow. 
In addition, fonts with a descent of and 1 cannot be underlined; this includes 
the default system font used on the GS. 

To determine the current style of an item, use GetMItemStyle: 

PushWord #0 ;space for result 

PushWord #267 litem ID number 

.GetMItemStyle 

PLft JP°P the result (a style word) 

The result is a stvle word. 



REMOVING MENUS 

To remove a menu definition from the system permanently, thus freeing up the 
memory it uses, first remove it from the system menu bar with DeletcMenu: 

PHA ;space for result (handle) 

PHA 

PushWord MenuID ;ID number of menu 

_GetMHandle 

_DeleteMenu 

Notice that GetM Handle is used here to determine the handle to the system menu. 
Of course, if you saved the handle returned by NewMenu, you could just call 
DeleteMenu alter pushing the handle on the stack. 
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Next, call DisposeMenu (this code' assumes that you have saved the menu handle 
at Menu! hull): 

PushLong MenuHndl jHandle to menu 
_Di spo seMenu 

Once you have disposed nt a menu like this, you cannot use it again unless you 
redefine it with NewMenu, 

To reinstall a menu that was removed with Delete Menu but that was not disposed 
of use the InsertMenu function described earlier in this chapter. 

Note that neither DisposeMenu nor DeleleMenu has an immediate effect on the 
appearance of the menu bar on the screen. To redraw the menu bar without the 
removed menu, call FixMeuulJar to recalculate the menu bar size, then call 
Draw Menu Bar. 

USER INTERACTION 

A vital part of any program using menus is the code that handles activity in the 
menu bar area in a manner consistent with Apple s user-interface guidelines. There 
are two general ways of doing this, depending on whether you are using a Task Master 
event loop or a GetNextEvent event loop. 

Using GetNextEvent 

Handling menu bar activity if you are using GetNextEvent requires the most work. 
The program in listing 7—3 shows what to do. When GetNextEvent returns a mouse- 
down event (code 1), it calls FindWindow to determine if the event occurred in the 
menu bar area, If it did, FindWindow returns a result of wlnMeuuBar (17) and the 
program calls MenuSelect 

MenuSeleet tracks the movement of the mouse until the mouse button is released. 
It manages all the pull-down menu chores, including highlighting appropriate menu 
titles and item names. It returns a result indicating which menu item was selected, 
if an\ 

Here is the calling sequence for MenuSelect. 

PushPtr TaskRecord ;Pointer to task record 

PushLong #0 ;0 - system menu bar 

_MenuSelect 

The task record used by this call is the GetNextEvent event record that returned 
(In- mouse-down event, followed by the long-word TaskData and TaskMask fields. 
MenuSelect returns its result in the TaskData field: the low-order word is the ID 
of the menu item selected, and the high-order word is the ID of the menu selected, 
(TaskMask is actually used by TaskMastcr only.) The program can then take whatever 
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action is appropriate for the menu item selected. If the result is 0. no menu item 
was selected. 

The program in listing 7-3 also checks for keyboard equivalents of menu items. 
As was mentioned earlier in this chapter, an item can he associated with a keyboard 
equivalent using the * special character. To select such a menu item, you just tap 
the appropriate key while holding down the Open-Apple key. 

To deal with keyboard equivalents, the program cheeks for key-down and autokey 
events. When it finds one of these events, it passes the TaskRecord to MenuKey 
for analysis, MenuKey. like MenuSelect. returns the ID of the menu item selected 
in the low-order word of the TaskDala field. If the keystroke did not correspond to 
the primary or alternate equivalent, MenuKey returns an ID ol 



Using TaskMaster 

It is much easier to deal with activity in the menu bar using TaskMaster than it is 
using GecNextEvent, because TaskMaster automatically calls FiudWinduw and 
MenuSelect to determine what menu item was selected. It also calls MenuKey to 

check for keyboard equivalents, All you have to do is make sure that menu-bar 
handling has been enabled in the Task Mask. The program in listing 7-4 shows what 
a TaskMaster menu-handling routine looks like. 

The event code returned by TaskMaster when a menu item has been selected is 
wlnMenuBar (17). This is the same code returned by FindWindow for a mouse- 
down event in the menu bar. The ID numbers of the selected menu and menu item 
are stored in the high- and low-order words of tin TaskData field of the Task Record, 
respectively 

Generally speaking, TaskMaster simply returns the ID number of the menu item 
selected — it does not attempt to process the selection in any way (that is up to the 
application). The exceptions involve desk accessor) items, which have menu IDs 
from 1 to 249. and special menu items, which have IDs from 250 to £55. 

If a desk accessory item is selected, TaskMaster automatically opens the desk 
accessory in question and returns a null result. If a desk accessory window is active. 
special menu items are processed by passing them to the desk accessory for action. 
The desk accessory handles the Close item (#255) by closing its window, Editing 
items (#250 to #254) may or may not be handled by the accessory see chapter 9] 
if they are not. TaskMaster returns a wlnSpccial (25) event code to give the appli- 
cation a chance to da something with it. 



Removing Menu Title Highlighting 

If the user selects a menu item, both MenuSelect and MenuKey highlight the title 
of the menu in which it appears- When processing of the commands ends, you 
should call HiliteMenn tn return the title to its normal appearance: 
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PushWord #0 ;0 - normal title 

PushWord TaakData+2 ;Menu ID number 

_Hi 1 1 t eMenu 

The first parameter is a Boolean parameter indicating whether the menu title is 
to be highlighted (true) or drawn normally (false). The value passed here is False 
SO the title is redrawn normally. The second parameter is the ID number 
of the menu. It is stored in the high-order word of the Task-Data field of die event 
record. 

COLOR AND THE MENU MANAGER 

By default, menu bars and pull-down menus are white and any text items inside 
them are black. The menu bar outline, menu outline, underlines, and dividing lines 
are also black. When items are highlighted, the text becomes white and the back* 
ground black. 

With the SetBarColors function you can change the colors the Menu Manager 
uses to display menu bars, menus, and the text items in them. The colors used for 
unseleeted items, selected items, and outlines can be set separately. 

Here is how to call SetBarColors: 

PushWord NewBarColor ;unselected color 

PushWord Newl nvertCol or ;aelected color 

PushWord NewOutColor ^outline color 
^SetBarColors 

Each of the three parameters defines the colors of two areas, as follows. 
PARAMETER BITS 0-3 BITS 4-7 

N ewBai Color Text color when Background color when item is not selected 

item is not se- 
lected 

NewlnvertCoIor Text color when Background color when item is selected 
item is selected 

NewOutColor [zero] Color of outline of menu and menu bar, 

underlines, and dividing lines 

Bits 8-15 must always be 0, unless you specify a negative parameter (bit 15 = 1). 
When a parameter is negative, the color scheme of a given attribute does not 
change. 

In 6 10 by 200 mode you can use color numbers from to 3. In 320-by-200 mode, 
you can use color numbers from to 15. The standard colors assigned to each 
number were given in table 6—1 in chapter f> 
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REFERENCE SECTION 

Table R7-1: The Major Functions in the Menu Manager Too] Set ($0F) 



Function Name 


Function 
Number 


Stuck 
Faramet 


Description of 
Parameter 


CalcMenuSize 


SIC 


NewWidth (W) 


Menu width (0= automatic) 






NewHeight (W) 


Menu height (Q= automatic) 






MenuID (W) 


ID of menu 


CheekMrtem 


S32 


Checkltcm (W) 


True = check/ False = 
nncheck 






ItemlD (W) 


ID of menu item 


Delete Mite in 


$10 


ItemlD (W) 


ID of menu item to delete 


DeleteMenu 


$0E 


MenuID (W) 


ID of menu to delete 


DisableMItem 


$31 


ItemlD (W) 


ID of menu item to disable 


DisposeMenu 


$2E 


MenuHandle 1 . 


1 kindle to menu to dispose 


DrawMenuBar 


$2A 


[no parameters! 




Enable MI tern 


$30 


ItemlD fW 


ID of menu item to delete 


FixMenuBar 


$13 


result (W) 


Height of menu bar 


GetM Handle 


$16 


result (L) 


Handle to menu 






MenuID (W) 


ID of menu 


GetMItemMark 


$34 


result iW'i 


Mark character (0=no mark) 






ItemlD (WJ 


ID of menu item 


GetMItemStyle 


$36 


result (W) 


Text style 






ItemlD iW 


ID of menu item 


HiliteMenu 


$2C 


HiliteFlag (W) 


True= highlight/False -normal 






MenuID (W) 


1 D of menu 
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Function 

F miction Name Number 

EnseitMItem $0F 



Stack 
Parameters 



InsertMeiw $0D 



Menu Key 






MenuSelect $2B 

Men uShtit Down $03 
Menu Startup $02 



NewMenu 



S2D 



SetBarColors |17 



Set M Item Name |23 



SetMeiniTitle $21 



AddltemPtr L 

InsertAftei (W 
MenulD(W) 
AddMenuHndl (L) 
InsertAftei (W) 
TaskRcePtr (L) 
Me miliar Ptr (L) 
TaskRcePtr (L) 
MenuBarPtr (L) 
[no parameters] 
UserID(W) 
DPageAddr (W) 
result I Li 
MfimList (L) 
NewBarColor (W) 
NewInvColor W< 
NewOutColor (W) 
NewItemStr (L) 
I ten. ID l\Vi 
NewTitleStr (L) 
MenuID (W) 



Description of 

Parameter 

Ptr to item definition to use 
ID of item to insert after 
ID of menu to contain item 
Handle to menu to insert 
ID of menu to insert after 
Ptr to task record 

Ptr to menu bar (0= system) 

Ptr to task record 

Ptr to menu bar (0= system 

ID tail for memory allocation 
Address of I page in bank 
Handle to menu ren ord 

Ptr to menu list record 

Normal item color 

Item color when selected 

Outline color 

Ptr to new menu item string 

ID ol menu item 

Ptr to new menu title string 

ID of menu 
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Function Name 


Function 
Number 


Steoifc 

Parameters 


Description of 

Parameter 


SetMItem 


$24 


NewLinePtr (L) 


Ptr to new item line 






ItemID (W) 


ID of menu item 


SctMItemMark 


$33 


Markltem (W) 


ASCII code for mark 
character 






ItemID <W) 


ID of menu item 


SetMItem Style 


$35 


TextStyle (W) 


New text style 






ItemID (W) 


ID of menu item 
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Listing 7-1: A Subrou tine for Defining; Menus und a Menu Bar 

»###«*•«•»••■««»**•***■•**«*•** *■••*♦*** 

• This subroutine shows how lo define • 

• standard Apple-F 1 le-Edi t menus and a • 

• system menu bar. * 

DoMenus START 

; Start defining the individual menus and adding them 
; to the menu bar. This is done from right to left order 
; for simplicity. 

PushLong *0 ;0 = system menu bar 

PushPtr MenuL3 -.Pointer to menu definition 

_NewMenu ;Define the Edit menu 

PushWord *0 -.Add to menu 
_ I nser tMenu 

PushLong #0 

PushPtr MenuL2 

_NewMenu -.Define the File menu 

PushWord *0 

_I nser tMenu 

PushLong *0 

PuShPtr flenuLI 

.NewMenu ; Define the Apple menu 

PushWord #0 

_| nser tflenu 

PushWord #1 ;Menu ID (1 ■ Apple menu) 

_FixAppleMenu ;Add DAs to Apple menu 

PHA 

FixMenuBar ;Set the menu aue 

PLA 

_DrawMenuBar -.Display the menu bar 

RTS 

; Me nu/ l t em lists: 

MenuLI DC C'»> •NNtX'.H'OD' ;Apple menu 

DC C'fAbout this program . . . \N25GV* , H ' 0D' 

MenuL2 DC C>> File VNE'.H'OD' ;File menu 

DC C'**Close\N255V' .H'OD* -.Special close item 

DC C'*»Quit\N2S7«Qq t p H'0D» 
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MenuL3 



DC 

DC 
DC 
DC 
DC 

DC 



C> Edit \N3' ( H'QD' ;Edit menu 



C'##Undo\N250V*Zz< ,H'OD' 
C'##Cut\N2S1 -Xx' ,H'OD« 
C'*#Copy\N252»Cc' ,H'OD' 
C ' ##Paste\N253+Vv' ,H'OD' 
C'**Clear\N25«P ,H'OD' 



; Special edit items 



DC 



C» . • 



;End of menu 



Listing 7-2: 



END 



Changing the Appearance of Items in a Menu Using Special 
Characters 



MenuL4 DC C>> Attributes \N4',H'0D' 

DC C'##Bold\N258B' ,H'0D' 

DC C'**I talic\N2S9J ' ,H'0D« 

DC C , **Underline\N260U l > H'0D» 

DC C'##A1I Attnbute5\N261BIU' ,H'0D' 

DC C '*#Disabled\N262D' ( H'0D> 

DC C'**-NN263D' .H'OD' 

DC C 'ifptar ked\N264C> ,HM3' ,H»0D' 

DC C'**Checked\N265» ,H'0D» 

DC C'Equivalent B\N266*Bb r >H ' OD 1 

DC C l #lrDividln9\N2G7V• ,H'0D' 

DC C "Normal I tem\N2G8' , H < OD* 

DC C • • ;End of menu 



Listing 7-3: Handling Menu Activity When Using a GetNextEvent Event Loop 



wlnMenuBar GEOU 



17 



In menu bar 



MenuDemo 


START 








Evt Loop 


PHA 










PushWor 


d *$FFFF 


-.All 


event s 




PushPtr 


TaskRec 








_GetNex 


tEvent 








PLA 




;Did 


anything happen? 




BEQ 


EvtLoop 


;No, 


so branch 




LDA 


what 


-,Get 


event code 




CMP 


#1 


; Mouse -down? 




BEQ 


F j ndWhere 


;Yes 


, so branch 




CMP 


#3 


; Key- 


-down? 




BEQ 


Equi vChk 


;Yes 


, so check for equivalent 




CMP 


*5 


; Auto- key? 




BEQ 


Equi vChk 


;Ves : 


i so branch 
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DoOther ANQP 

; [handle other typei of events here] 

BRL EvtLoop 

;Check for keyboard equivalents of menu items: 

EquivChk PushPtr TaskRec 

PushLong #0 j0 ■ system menu bar 

_P1enuKey 

LDA TaskData ;menu item selected 7 

BNE DoMenu iYes, so handle it 

LDA what ;6et code back 

BRL DoOther 

?Find out where the mouse-down took place: 

*, Space for result 

•.return window pointer here 

;push point to check (global) 

; Get result code 

; 1 n menu bar 7 
;Ve5, 50 branch 

i [handle mouse activity in other areas here! 

BRL EvtLoop 

WasMenu PushPtr TaskRec 

PushLong #0 ;0 * system menu bar 

„M'enu5elec t ".Determine which menu item 

; Handle menu selections: 

DoMenu LDA Task Data ;Get menu item ID 

BEG EvtLoop ; Branch if nothing selected 

CMP #256 ;Is it a special item (ID < 256} 7 

BCC DoMenul ;Yes, so branch 

; This code assumes that standard menu items are numbered 
\ consecutively from 256. 
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FindWhere 


PHA 




PushPtr TheWindow 




PushLong where 




_F i ndWi ndow 




PLA 




CMP 'wlnMenuBar 




BEQ WasMenu 





AND 


#*00FF 




ASL 


A 




TAX 






JSR 


(MenuTable , X ) 




BRA 


TitleOff 


DoMenul 


JSR 


DoSpec ial I 


TitleQff 


PuahWor 


d *0 



•.Convert to base 

;x2 to step into table 

; C a 1 1 item subroutine 



;0 = title highlighting off 
PushWord TaslcData + 2 ; The menu ID la at TaskData+2 
_Hi 1 t teMenu 

BRL EvtLoop 

5 Table of subroutine addresses, in numeric order: 

MenuTable DC I'DoItem256' 
DC PDoItem257' 
DC I r DoItem258' 

Handle special editing items, close item here: 
Normally would pass these to the Dealt Manager 
with SyatemEdit, 

DoSpeciaiJ ANDP 

CMP #255 ;Close item? 

BNE DoEdit ; No , so it must be Edit item 

; Put code here to close the active window. 

RTS 

; Here is where to put code to handle the special edit items. 
; The ID. codes are 250 (Undo), 251 (Cut), 252 (Copy), 
; 253 (Paste), and 254 (Clear). 



; Convert to base 
;x2 to step into table 



DoEdit 


SEC 






SBC 


*25Q 




ASL 


A 




TAX 






JMP 


(EditTabl 


EditTable 


DC 


3 "DoUndo 1 




DC 


1 'DoCut ' 




DC 


I ' DoCopy • 




DC 


1 ' DoPaa te 




DC 


1 'DoClear 
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DoUndo 


ANOP 


DoCut 


ANOP 


DoCopy 


ANOP 


DoPaste 


ANOP 


DoClear 


ANOP 




RTS 



TheWindow DS 1 
vGetNex tEvent task record; 



TaskRec 


ANOP 




What 


DS 


2 


Meaaage 


DS 


-• 


When 


DS 


-'! 


Where 


DS 


4 


Modi f i era 


DS 


2 


Tas kData 


DS 


4 


Tas kFlosfc 


DC 


I 



14 f S00001FFF' 



;Returned by FindWindow 



; Event code 

; Event result 

;Ticks since startup 

;Mouse location (global) 

;Status of modifier key! 

; Task Mas ter data 

; Task Maa ter handles all 



END 



Listing 7-4: Handling Menu Activity When Using a Task Master Event Loop 



wlnMenuBar GEQU 17 
wlnSpecial GEQU 25 



MenuDemo 


START 




EvtLoop 


PHA 






PuahWor 


d #SFFFF 




PushPtr 


TaskRec 




_Tas kMas ter 




PLA 






CMP 


#wl nMenuBar 




BEQ 


DoMenu 




CMP 


*wl nSpecial 




BEQ 


DoMenu 



; In menu bar 

;ln special menu item 



; A 1 1 events 



;Get result code 

;Menu item selected? 
; Yes , so branch 
^Special menu Item? 
', Yes , so branch 



; handle other result codes here 

BRL EvtLoop 
\ Handle menu selections: 
DoMenu LDA TaskData 



CMP 



#256 
DoMenul 



;Is it a special item (ID < 256)' 
♦.Yes, so branch 



264 Using Pull-down Menus 



; This code assumes that standard menu items are numbered 
; consecutively from 256, 

;Convert to base 

;x2 to step into table 

:Call item subroutine 





AND 


ftflOFF 




A5L 


A 




TAX 






JSR 


(Menu Table , X } 




BRA 


TitleDff 


DoMenul 


JSR 


DoSpec lal 1 


TitleOff 


PushWor 


d #Q 



;0 = title highlighting off 
PushWord TaskData+2 ;The menu ID is at TaslData+2 
_Hi 1 1 tetlenu 

BRL EvtLoop 

; Table of subroutine addresses, in numeric order: 

MenuTable DC I'Doltem2SG' 
DC I'Doltem257« 
DC PDoItem258' 

5 Handle special editing items, close item here: 

DoSpec la II ANOP 

CMP *255 iClose item? 

BNE DoEdit ;No, so it must be Edit item 

; Put code here to close the active window. 

RTS 

; Here is where to put code to handle the special edit items. 
; The ID codes are 250 (Undo), 251 (Cut), 252 (Copy), 
; 2S3 (Paste), and 25-4 (Clear). 



;Convert to base 

1X2 to step into table 



DoEdit 


SEC 






SBC 


'250 




ASL 


A 




TAX 






JMP 


(EditTable 


EditTable 


DC 


I 'DoUndo' 




DC 


I 'DoCut ' 




DC 


I 'DoCopy ' 




DC 


I 'DoPaste 1 




DC 


[ 'DoClear ' 
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Do Undo 


ANOP 


DoCut 


AN DP 


Do Copy 


AN DP 


DoPaste 


ANOP 


DoClear 


ANOP 




RTS 



■-, Task Master task record: 



TaskRec 


ANOP 




What 


D5 


2 


Me 5 sage 


DS 


■1 


When 


D5 


4 


Where 


DS 


3 


Modi f ier 5 


DS 


2 


Task Data 


cs 


4 


TaskMask 


DC 


3 



14'$00QQ1FFF« 



•.Event code 

;Event result 

;Ticks since startup 

; Mouse location (global) 

;Status of modifier keys 

jTaskMaster data 

; Task Master handles all 



END 
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CHAPTER 8 



Using Dialog 
and Alert Boxes 



Apple's standard user-interface guidelines describe two special types of windows 
called dialog boxes and alert boxes The general appearance of these types of 
windows is shown in figures 8-1 and 8-2. Dialog boxes are conventionally used to 
request certain types of input from the user. They can include several data input 
fields, containing such items as a line of text that can be edited, cheek boxes, 
buttons, and scroll controls. They can also contain static Reins which cannot be 
modified, such as text strings, irons, and pictures. 

An alert box, as its nam*' suggests, normall) warns a user of the consequences of 
a proposed action which might result in the destruction or loss of data. In a typical 
application, an alert box contains OK" and "Cancel " buttons that can be clicked to 
either verify the action or abort it. For instance, if you are running a disk utility 
program and you try to format a disk, you will invariably see an alert bos warning 

'i that the operation will destroy data and asking you to verify that you wish to 
proceed. 

Alert boxes can he used to display status information as wolf Most 'About... 
items in the standard Apple menu use alert boxes to display authorship and copyright 
information, for example. 

The main difference between alerts and dialogs is that alerts do not contain any 
user-alterable input areas, such as a text editing box. They contain only static items 
and one or more buttons yon can click to dismiss the alert and continue with the 
main application. 

To create and control dialog and alert boxes, you must use a tool set called the 
Dialog Manager (tool set 21). This chapter investigates the Dialog Manager and 
explains how you can use it in your applications. 
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Figure 8-1, A Dialog Box 











Communications Parameters 






Baud Rate: O300 ($1200 O2400 






Data Bits: ®8 07 






Stop Bits: ®1 02 






Parity: ©None OEwen OOdd 






D Filter EE3 XON/XOFF □LineDelasi 




Download file: BE (f .„ % 




UU 









Figure 8-2. An Alert Box 



A 


Do you want to erase PROGRRH.BflS? 




E 


Cancel A 



STARTING UP THE DIALOG MANAGER 

To start up the Dialog Manager, pass the ID of the program (the one returned by 
MM Start up) to DiafogStartup: 



PushWord MyJD 
_DialogS tartup 



^Program ID 
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Calling DialogStartup prepares the Dialog Manager for activity and initializes all 
internal variables and routines. 

Because the Dialog Manager uses QuickDraw II, the Window Manager, the 
Menu Manager, the Control Manager, and the LineEdit tool sets, you must start 
them up before calling DialogStartup. The STANDARD, ASM program in chapter 
3 takes care of this for you. 

The only tool set in this list that has not been discussed before is LineEdit, a 
tool set used for editing lines of text. To start it up, you must provide one page in 
bank $00 that it tan use as a direct page, Here is the start-up sequence: 

PushWord MylD ;ProgramID 

PushUlord DPSpace -,Addre55 of one page DP area 

_LEStar tup 

The standard LineEdit editing commands will be examined later in this chapter. 

When you have finished using the Dialog Manager, shut it down with the 
DistlogS hutDown function. This function expects no input parameters and returns 
no results. You can shut down LineEdit by calling LEShutDown in the same way. 

CREATING DIALOG BOXES 

Two general classes of dialog boxes can be implemented on the r:s: modal and 
modeless. A modal dialog box is one that, once displayed, handles all keyboard and 
mouse events until the user dismisses the box by clicking a button in the box 
Mouse clicks outside the dialog box are ignored, so you cannot pull down a menu, 
select another window, or use a desk accessory until the modal dialog box is 
dismissed. In fact, this is how the modal dialog box gets its name; when you are 
using it, you are confined to a special operating mode until a button is clicked. 

A modeless dialog box, on the other hand, is just like any other window on the 
screen, and TaskMaslcr treats it as such. It has a goaway box and a title bar, but no 
zoom box, grow box. or scroll controls. The user is free to switch between the 
modeless dialog box and any other window on the screen in the usual way. You can 
remove a modeless dialog box from the screen just as you would any other window: 
by clicking its goaway box or selecting the Close item from a File menu when the 
window is active. 

Modal and modeless dialog boxes are defined and created using the same general 
programming techniques. The difference in their behavior arises because different 
instructions are used to interact with them while they are on the screen. 

Modal Dialog Boxes 

To create a modal dialog box, you can use either NewModal Dialog or GetNew- 
Modal Dialog, The main difference between the two is that all the parameters for a 
NewModal Dialog call are pushed on the stack. With OetNewModal Dialog, the only 
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parameter is a pointer to a dialog template; the template contains all the information 
needed to display the dialog box correctly. 

You Will probablv prefer to use GclXewModal Dialog, because it requires less 
work, Here is how to call it: 

p HA -.Space for result (long) 

P HA , it 

PushPtr DlogTemp -.Pointer to dialog template 

GetNewModalDialog 
PopLong DialogPtr ;P°p dialog pointer 

An example of how to use GetNewModalDialog is shown in listing 8-1. It creates 
the dialog box shown in figure 8-1. 

GctNcwVlodalDialog draws the dialog box on the screen, but does not actually 
draw the items inside the box (that is done by ModalDialog; see below). The result 
returned by GetNewModalDialog is a pointer to the internal record that the Dialog 
Manager maintains in order to keep track of the modal dialog box. Save it for use 
with other dialog -related functions 

The dialog template required by GetNewModalDialog is a variable length table 
containing information about the size of the dialog box and the items it is to contain. 
Here is its structure: 

DlogTemp ANQP ■ i„^i\ 

DC I't.l.b.r' ;Content rectangle (global) 

;Non-zero ■ Visible 
-.Reference constant 
• f Pointer to 1st item template 
-.Pointer to 2nd item template 

-.Pointer to Nth item template 
-.Long zero terminator 

The template begins with the rectangular dimensions of the content portion of the 
dialog box, in global Coordinates, These dimensions are followed by a Boolean value 
that indicates whether or not the dialog box is to be visible; you should make tins 
vain, non-zero (true) so that the box will appear on the screen. The third parameter 
is a reference constant that the application can use lor anything it likes. 

Next conn- a series of pointers to the templates for the various items to be drawn 
inside the dialog box. These item templates will be discussed in the next section. 
The last item pointer is followed by a long zero, which marks the end of the list. 

[f you choose to use NewModalDialog. von must provide three input parameters: 
a pointer to the content rectangle, the visible Hag. and the reference constant 

p HA ;Space for result 

P H A 

PushPtr BoundsReet -.Pointer to rectangle def 
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ANDP 




DC 


1 't ,l,b,r 


DC 


1 'SFFFF' 


DC 


14*0' 


DC 


14' Iteml ' 


DC 


14' It em2 ' 


DC 


14" ltemN' 


DC 


1 4 ' Q ' 



PushWord #S8000 ^Visible BooleaTi 

PushLong *Q ■Reference constant 

_NewModalDia log 

PopLong DialogPtr ;Pop dialog pointer 

RTS 

BcundsRect DC I*t,X,b y r l ;Rectangle definition 

Notice that the item definitions are missing- Alter calling New Modal Dialog, you 
must attach items to the dialog record using the XowDltem or GetNewDItem 
functions. Both are described later in this chapter. 

ITEM TYPES 

As mentioned above, the dialog template you pass to GetNewModalDialog contains 
pointers to the definition templates foi each item thai is to appear in the dialog box. 
The items supported by the Dialog Manager are us follows; 

• Button 

• Check box 

• Radio button 

• Stroll liar 

• User-defined control (two types) 

• Static text (up to 255 characters) 

• Long static text tup to 32,767 characters) 

• Editable line 

• Icon 

• QuickDraw II picture 

• User-defined item 

Tli standard symbolic names lor these items are shown in table 8—1. Figure 8-3 
shows what the standard item types look like. 

The template tor any item has the Following structure: 



ItemTemp flNDP 

DC I'lteflilD' 

DC 14' t , 1 ,b,r» 

DC I ' I temType ' 

DC 14" ItemDescr ' 

DC I'ltemValue' 



Unique ID code for" the item 

The item rectangle 

I tem t ype code 

Item descriptor (item specific; 

Initial value of item 
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Table 8-1: Item Type Codes for Dialog and Alert Boxes 

Code 



Symbolic Name 

Button 1 tern 

Checklteui 

Radio] te in 

Scroll D ail tern 

I'serCllItem 

StatTeKt 

LongStatText 

EditLine 

Icon Item 

Pic I tern 

Userltem 

UserCtlltemS 

ItemDisahle 



Description 



SOOOA 

S(HK)B 

8000C 

SOOOD 

$O0QE 

SOOOF 

S001Q 

$0011 

$0012 

$0013 

$0014 

$0015 

$8000 



Button control 
Check box control 
Radio button item 
Scroll bar control 
User-defined control 
Static text 
Long static text 
Editable line 
Icon 

QuickDraw II picture 
User-defined item 
User defined control 
Add this to disable 



note; Add uV constant Item Disable u> ihc code for an item to disable thai item 



DC I'ltemFlag' (Display flags (item specific) 
DC 14 ' I temColor ' ^Pointer to item's color table 



The ItemlD is an identification number you assign to the item. No other item in 
the dialog box may use the same number. 

Item Keel is the rectangle in which the item will be drawn. The coordinates are 
in standard top, left, bottom, right order. You will find that the most frustrating 
aspect of defining an item is adjusting its rectangle so that it appears in the correct 
position and does not overlap other items. 

ItemType is the code the Dialog Manager uses to identify- the type of control 
you are defining. The sallies for each type of item are shown in table 8-2. The 
symbolic names for these codes are defined in the STANDARD. ASM file with 
GEQU directives 

The meaning of ItemDescr is different for each item type. It is generally a pointer 
to a data area associated with the item. For a static text item, lor example, it points 
to the text string. 
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Figure 8-3, Common [terns Used in Dialog Boxes 



Button 



#Icon 



Editable Text 



[x] Check Box On 
□ Check Box Off 
(§) Radio Button On 
O Radio Button Off 



@ 



Scroll Bar — > 



Item Value contains the initial value of the item. As will be discussed, cont 
items like check boxes, radio buttons, and scroll bars have values associated with 
them . 

The primary purpose of ItemFIag is to indicate whether the item is to be visible 
or invisible. For visible items, bit 7 must be 0; for invisible items, bit 7 must be L. 
Certain other items, namely buttons and scroll bars, use other bits in ItemFIag to 
control their appearance. Radio buttons use six bits as a family number so that 
related radio buttons can be dealt with as a group. 

ItemColor points to a color table for the item. Set it to to use the standard 
color table. 

Each of the item types supported by the Dialog Manager i:s described below. 



Buttons 

A button item (Buttonltem) is a rectangle that the user can click to dismiss the 
dialog box. The application should react to the click by saving the values of any 
other items in the dialog box. removing the box from the screen, and then taking 
whatever action is appropriate for the button selected. 

The ItemDeser field in an item template points to the name of the button 
(preceded by a length byte); the name is drawn inside the button rectangle. 
Item Value is not used. 
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Table 8=2: The Contents of the IteniDeser, ItemValue, and ItemFlag Fields in 
an Item Template 



Item Type 



Item Type 



Button Item 

Radioltem 
Scroll Bar! tern 



ttemDeser 



llemValue 



Buttonltem Pointer to item name 

Checkltem Pointer to item name 

Kadinltem Pointer to item name 

ScrollBarltem Pointer to action procedure 

UserCtlltcm Pointer to control procedure 

S ta tTc xt P( rinter to static strin g 

LongStatText Pointer to text 

EditLine Pointer to default string 

Iconltem Handle to icon definition 

Ficltem Handle to picture 

L st litem Pointer to definition procedure 

UserCtlItem2 Pointer to control parameters 



[Not used] 

o=oa; i=on 

Q=ofif, l=on 

Initial value: to 290 

Initial value 

[Not used] 

Text length: to 32767 

Maximum length: to 255 

[Not used] 

[Not used] 

[Not used] 

Initial value 



ItemFlag 



Bit 0:1= bold outline, = normal 

Bit 1:1 = square-corner, = round-corner 

Bits 0-6 : family number (0 to 127 1 

Bit 0:1 = up arrow on scroll bar 

Bit 1:1 = down arrow on scroll bar 

Bit 2 : 1 = left arrow on scroll bar 

Bit 3 : 1 = right arrow on scroll bar 

Bit 4 : 1 = horizontal scroll bar, = vertical 



NOTE: For all other items, set bit 7 of ItemFlag to 1 to make the item invisible. 

The button is usually a rounded-corner rectangle, but it can also be a square- 
cornered rectangle with a drop shadow if bit 1 of ItemFlag is set to L. 

Most modal dialog boxes and alert boxes contain at least one button so that they 
can be dismissed in accordance with the user-interface guidelines. 

A default button is one which may be selected by pressing the Return kev. By 
convention, the default button is enclosed by a dark, black border so that it can be 



274 Using Dialog and Alert Boxes 



teadilv identified. If vou define mure than one button in a dialog box, the one most 
likely to he selected should be made the default so it can be selected easily from 
the keyboard. 

For modal dialog boxes, a Buttonltera with an ID of 1 is always the default item. 
Such a button is typically labeled as the OK button. For alert boxes, a button with 
an ID of either 1 or 2 in the item list can be designated as the default when you 
create the alert's item list. These buttons are usually marked as the "OK" and 
"Cancer buttons. 

Cheek Boxes 

A check box item (Checkltcm) is always associated with a parameter that can be in 
one of two states: on and off. selected and not selected, high and low, and so on. A 
check box appears as a small square in the dialog box When it is on. its value is I, 
and it has an X drawn in it. When it is off, its value is 0, and the square is hollow. 
The ItemDcscr field in a check box template contains a pointer to the name of 
the check box. The name is drawn to the right of the cheek box. inside the item's 
display rectangle. ItemValue contains the initial value of the check box and can be 
either 1 Ion) or (oil 

Radio Buttons 

Radio button items (Kadioltem) usually appear in groups of two or more, with eat b 
radio button representing a different value that ma) be associated with one particular 
parameter of interest to the application. They appear as small circles in a dialog 
box, and the one that is on (value 1) has a smaller black circle inscribed m it The 
radio buttons name, pointed to by IteniDesci, appears to the right of the button. 

A radio button derives its name from the feet that when you select one by clicking 
it. all other buttons in the group are turned oil just like when you select a station 
on a standard car radio. 

It is possible to assign associated radio buttons to the same family so that when 
one is turned on all the others will automatically turn oil. To do this, put the family 
number (from to 127) in bits through 6 of ItemFlag, 

Scroll Bars 

Scroll bars have ahead) been discussed in connection with the Window Manager. 
You can use them to reflect the value, in pictorial form, of any measurable quantity 
that might take on a range of values. For example, the position of the thumb in a 
vertical scroll bar might represent the amount office space on a disk. 

The ItemDescr field of a SerollBarltem is a pointer to an action procedure that 
is called when any part of the scroll bar is selected. For information on how to 
design such a control, refer to the Apple Has Toolbox Reference. If the pointer is 
0, the Dialog Manager does nothing special 
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A scroll bar can take on values from to 290; this range is reflected by the 
position of the thumb on the bar relative to the end points. ItemValue contains the 
initial value of the scroll bar. 

The appearance of the control can be set using bits to 4 of I tern Flag. These 
bits have the following meanings; 

bit I = draw up arrow cm scroll bar 
bit I 1 = draw down arrow on scroll liar 
bit 2 1 = draw left arrow on scroll Inn- 
bit 3 1 = draw right arrow on scroll bar 
bit 4 1 = horizontal scroll liar. (J = vertical 

The IternFlag value for a horizontal scroll bar with arrows would be $0GTC. for 
example 

User Control Items 

The first type of user control item (UserCtlltem) is a custom control designed in 
accordance with the specifications of the Control Manager. For these types oF items. 
ItcmDcscr points to a control definition procedure, and Itein Value contains the 
initial value of the control. For instructions on how to design custom controls, refer 
to the Control Manager chapter of the Apple lies Toolbox Reference. 

The other type of user control item i L ! serCllltem2> is useful if you want to 
implement any control defined by the Control Manager. ItemDeser points to a 
parameter block that contains the address ot the definition procedure for the control* 
a pointer to the title ol the control, the view size, and the data size. 

Static Text and Long Static Text 

A regular static text item (StatTexO is a string of up to 255 characters to be drawn 
in the dialog box. It is said to be static because you cannot edit it, A long static text 
item (LongStatTcxt) is similar to a Stat Text item, but it can hold up to 32,767 
characters. Both these items are used for such purposes as displaying commands, 
displaying explanatory messages, or posing questions. 

For a StatTexl item, the lleinDescr field in the item template- points to the string 
(preceded by a length byte) that contains the static test. The ItemValue field is 
undefined. For a LongStatTcxt item, ItcmDcscr points to the start of the text (no 
preceding length byte). ItemValue contains the length of the string. 

To define a static test item that is to be drawn on more than one line, you must 
insert carriage return codes (ASCII SOD! 1 inside the text string. The Dialog Manager 
does nol automatically wrap text at the item rectangle boundary. 

Be careful to make the item rectangle deep enough to hold the text. If it is too 
shallow, the text will be clipped. If you are drawing a single line ot text using the 
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system lout, the depth should be at least nine rows {the ascen t+ descent + leading 
of the font). 

It is often convenient to be able to change the precise wording of a static text 
item alter it is initially defined, by inserting filenames or phrases which cannot be 
predicted in advance. The easiest way to do this is bo use the "0, "1, "2, and "3 text 
place holders when you first define the static text item. 

You can assign a text string to each of these place holders to ensure that when 
the dialog box is drawn, the strings are substituted for the place holders. The 
instruction to use for this is _ParamText: 

PushPtr StringO ;5tring for "0 

PushPtr Stringl ;String for "1 

PushLong #0 ; (Don't change *2 string) 

PushPtr String3 ^String for "3 

_ParamText 

StringO STR 'placeholder 0' 
Stringl STR 'placeholder 1' 
String3 STR '4th placeholder 1 

If you do not want to change a particular string, push a long word on the stack 
instead of a pointer to the string, This was done for the "2 place holder in the 
example. 

Suppose you use a dialog box to ask for verification of a disk formatting operation. 
Instead of using a general static text item like "Are you sure you want to erase the 
disk?", you can define an item such as Are yon sure you want to erase A 0?" You 
can then use _PaianiText to substitute for *0 the actual name oi the disk selected. 
This must be done before the dialog is displayed, of course. 

Editable Line 

An editable line item (EditLine) is a single line of text that may be edited using the 
standard editing techniques supported by the LineEdit tool set. The texl can be up 
to 255 characters long and is enclosed by a rectangle. 

You must be careful to ensure that the height of the rectangle for an EditLine 
item is at least two rows greater than the height of the font. If you arc using the 
system font, for example, the rectangle height must be at least 1 1 rows. If the 
rectangle height is lower, no characters will appear. 

The standard LineEdit editing techniques arc as follows; 

An insertion point can be selected by clicking the mouse at any position in the 
text string. The insertion point is marked by a blinking vertical bar; subsequent 
characters will be placed at this location. 
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A range of text can be selected by dragging the mouse across the text (Selected 

text appears as white characters against a black background.) A selection range 
is deleted when a subsequent character is entered. 

A word can be selected by double-clicking the mouse anywhere in the word, 

All the text can be selected by triple-clicking. 

A selection range can he extended by clicking while holding down the Shift 
key. 

Pressing ControbX wiU erase the entire line. 

Pressing Control-Y will erase everything from the current insertion point to the 
end of the line, ii a selection range is active, it is deleted. 

The left- and right-arrow keys can he used to move the insertion point back and 
forth in the text line. 

Pressing Control-F will delete the character at the insertion point or will delete 
the selection range. 

Pressing Delete will delete the character to the left of the insertion point arid 
move all the characters to the right of the insertion point one position to the 
left, or will delete i lion range. 

Pressing any other key will insert that key character at the insertion point; if a 
range is selected, the characters in the range will be deleted and replaced by 
the key character. 

Opcn-Apple-X, Open-Applc-C, and Open-Apple-V can be used to perform cut, 
copy, and paste operations, all of which involve a data area called the clipboard, 
Cutting transfers the selection range to the clipboard and removes it from the 
line. Copying does the same thing, hut without removing it from the line. 
Pasting involves transferring text from the clipboard to the line at the insertion 
point (if a selection range is active, the selection is deleted first). 

Using an editable text item for user input makes it unnecessary for von to write 
your own line editor. 

For an EclitLine item, ItemDescr is a pointer to the string (preceded by a length 
byte) that will be shown when the dialog box first appears. The Item Value Held 
contains the maximum length of the string; the possible choices are to 255. 

When a dialog box is drawn, the lirst KditLine item is totally selected so that 
you can delete it quickly by pressing a key to enter a new string. If there is more 
than one editable text box item, you can use the Tab key to move from one to the 
next. If you are in the last text box when you press Tab. yon will go to the first box. 

As will be discussed later, the Dialog Manager contains functions you can use to 
change the EditLine text, to determine its contents, and to select any portion of it. 
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Icons 

An icon (Iconltein) is a static item that defines a small rectangular image on the 
screen. The ItemDescr field in a template contains a handle (not a pointer) to the 
icon definition. Item Value is not used 

An icon definition begins with the pixel dimensions of the icon, in rectangle 
form. (The width of the icon must be a multiple ol \S.) Following the rectangle are 
the bytes defining the hit image of the icon. When designing an icon, keep in mind 
that there are two bits per pixel in 640-by-200 mode and four bits per pixel in 320- 
by-200 mode. 

Here is the definition for an icon in 640-by-200 mode that looks like an asterisk: 



; I c o n rectangle 

;Bit image defining each row 

j (2 pi xeis/nibble in 640 mode] 



My 1 con 


ANO-P 






DC 


1 '0, 0,9,15' 




DC 


H'FFFOFFFF' 




DC 


H'OFFOFFOF' 




DC 


H'FOFQFOFF* 




DC 


H'FFOOOFFF' 




DC 


H'OOOOQOOF » 




DC 


H'FFOOOFFF' 




DC 


H'FOFOFQFF' 




DC 


H'OFFOFFOF' 




DC 


H'FFFOFFFF" 



Remember that two U bits refer to a black pfetel on the 54(>-by-200 screen, and two 
1 bits refer to a white pixel. 

Pictures 

A picture item (Picltcm) contains a handle to a QuickDraw II picture in its 
ItemDescr field. The Item Value field is not defined. 

User Item 

A user item I I'serJtem) is one whose appearance and behavior is defined by the 
application. For such an item, ItemDescr points to an item-definition procedure 
and Item Value is not used. 

The Dialog Manager calls an item-definition procedure with a JSL instruction 
after first pushing two parameters on the stack: a pointer to the dialog (long' and 
the ID number of the item to draw (word). This information is provided so that you 
can use the same item-definition procedure to handle many user items and dialog 
windows. 

Alter the procedure does what it is designed to do, perhaps drawing a fancy 
border or playing a time, it must remove the input parameters from the stack and 
return. Here is the code fragment you will need to do this; 
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LDA 2,E {Remove parameters by moving 

STA 8,S ; the return address up 

LDA 1 ,5 -, by 6 bytes 

STA 7 , S 

TSC ;Addi G to the stack pointer 

CLC 

ADC #6 

TCS 

RTL 

The procedure ends with RTL because it is called with a JSL instruction, 

DISABLING ITEMS 

Any item in a dialog can be marked as disabled hy adding the ItemDisahle constant 
(S8000) to its item type code. Disabled items still look the same, but user activity 
in them is not reported to the application. It is a good idea to disable static items 
like icons, pictures, and text so that the application does not have to bother dealing 
with mouse activity in them. 

ADDING ITEMS TO DIALOG BOXES 

If you have created a dialog box with NewModal Dialog, you need to add items to 
it before anything useful will appear on the screen. Even if you have used Get- 
NevvModal Dialog with predefined items, you may want to add new items to react 
to changes in standard operating conditions. 

To add an item, use either Gel NewDItem or NewDItem. Using GetNewDItem 
IS the easiest: 

PushLong theDialog ;Push dialog pointer 

PushPtr 1 temTemplate ;Push pointer to item template 

.GetNewDItem 

As you can sec, GetNewDItem expects to find the item parameters in a template. 
The form of this template is the same as described in the previous section. 
NewDItem expects you to push the item parameters on the stack instead; 

PushLong theDialog ; D i a 1 a g pointer 

Push-Word ItemID ;Item ID number 

PushPtr JtemRect ;Pointer to item rectangle 

PushWord ItemType ; I tern type code 

PushLong ItemDescr ;Item descriptor 

PushWord ItemValue ;ltem value 
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PushWord ItemFlag ;ltem flag 

PuahLong ItemColor jPtr to item color table (Q=default) 

_NewD I tern 

CHANGING ITEM ATTRIBUTES 

Many Dialog Manager Functions can be used to rend and change attributes of the 
items in a dialog box item list 

Ge t I Tex t Return text of a Stat Text or EditLine item 

Set I Text Set the text of a StatTexl or EditLine item 

Sel I Text Set the selection range of an EditLine item 

GetDI t emType Gel the item type code for an item 

SetDI t emType Set (he item type code For an item 

GetDI temBox Return the display rectangle for an item 

SetDI t emBox Set the display rectangle for an item 

GetDefButton Return the ID of the default item 

SetDef But t on Set the ID of the default item 

GetD I t emVa lue Return the item Value for an item 

SetDI t emVa lue Set the itemValue for an item 

HideDI tem Erase an item 

ShowDI tem Displa\ ,i hidden item 

FindDI tem Return the ID of the item at a given point 

DisableDItem Disable an item 

EnableDItem Enable an item 

Of these functions, only GetJText, SetlText. SellText, GetDItemValue, and Set- 
Dltem Value are commonly used b) applications- You may find a need for the others 
if you need to write a complex filter procedure (see the discussion of filter procedures 
below). 

This section discusses ways of using this group of five major attribute commands. 
For information on the others, refer to the Apple lies Toolbox Reference. 

Dealing with Text Items 

It is often necessary to determine the text associated with a particular EditLine 
item so that the application can take the user's input and deal with it. For this, use 
GetlText: 

PushLong theDialog ^Dialog pointer 

PushWord item ID ;ID number of item 

PushPtr theText ;Pointer to string area 

_Get JText 
RTS 

theText DS 2S6 ;Space for returned string 

Changing Item Attributes 281 



The space you reserve lor theText must be one byte greater than the maximum 
length of the text item permitted. The extra byte is for the leading length byte. You 
can also use GetlText with a StatText item if you wish 

fa change the text of a StatText or Edit Line item, use SellText: 

PushLong theDialog ■» Dialog pointer 

PushWord itemID ; I tem ID number 

PushPtr MyText ; The new text string 
SellText 



MyText STR 'This is a new string" 

The string at MyText must be preceded by a length byte. Von can also change the 
text oi an item using the ParamTexl command described earlier in this chapter. For 
this to work, the item text must contain place holder characters ot the farm "0, "1, 
'2. and "3. 

Another thing you can do is preselect all or a portion of an EditLine item. 
Selected text is highlighted in white letters on a black background and is deleted 
and replaced when you type a character from the keyboard. If the item contains a 
default string, you will probably want to select the entire string, so the Dialog 
Manager does thi:, for you, That way, the default will disappear when the user types 
a character to change the entry. 

Suppose the user is to enter an EditLine item that ends with a filename suffix of 
".ASM". If you display a default, you may wish to highlight everything but the suffix 
SO that the user does not have to retype the suffix if he enters a new name. Here 
is how you arrange for the proper highlighting using SetlText; 

Push Long theDialog *, Dialog pointer 

PushWord itemID litem ID number 

; Starting char, position 

}Get length of name 
;5ubtract suffix sire 
;Ending character position 



The starting and ending position parameters passed to SeHText run from up to 
the maximum size of the text string A value refers to a position to the left of the 
first character, 1 refers to a position to the left of the second character, and so on. 
If the starting and ending positions are equal, a blinking vertical bar appears at that 
position. Typed characters are inserted at this point. 
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PushWord 


#0 




SEC 






LDfi 


Name 


Len 


SBC 


#4 




PHA 






_SelITex 


t 





Reading and Changing the Item Value 

To read the current numeric value of an item, use Get Dltem Value as follows; 

PHA ; Space for result 

PushLong theDialog ;The dialog pointer 

PushWord itemID ;The ID of the item 

_6etDItemValue 

PLA ;Get the result 

Of course, this function is useful only for those items that use the Item Value field 
in the item template. For check boxes and radio buttons, the value can be (off) 
or 1 (on). Other values are possible for scroll bar and user control items. For a 
LongSlatText item, the value is the length of the text. 

I se SetDItem Value to assign a particular value to mi item. You will use it most 
often to select and deselect check boxes and radio buttons. For example, if you 
detect a mouse click in a check box that is off, you would turn it on [put an X in it) 
using the following instructions 

PushWord #1 ;Hew value (1=on) 

PushLong theDialog -.Dialog pointer 

PushWord itemID ;ID of dialog item 
_SetDlteroValue 

When you turn on a radio button item like this, the Dialog Manager automatically 
turns off all radio button items with the same family number. This is in keeping 
with the user-interface guidelines, which insist that only one radio button in a group 
may be on. 

USING DIALOG BOXES 

The proper way to handle a dialog box once it is on the screen depends on whether 

it is a modal or modeless dialog box. 

Modal Dialog Boxes 

As soon as you define a modal dialog box on the screen with NewModal Dialog or 
GrtNewModal Dialog you must call ModalDialog to monitor events within the box 
and get a result indicating what item was selected. You can then deal with the result 
as yon see fit before calling ModalDialog once again to get more input or dismissing 
the dialog box if a button was selected. 

To dismiss a box, call Close Dialog to erase it from the screen. This function 
requires only one parameter, a dialog pointer 
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To use ModalDialog, push space for a word result and then push the address of 
a filter procedure: 

PHA ;Space for result 

PushPtr FilterProc ^Pointer to filter procedure 

_ModalDia log 

PLA *1D of item selected 

A filter procedure is a subroutine Modal Dialog calls after it detects an event but 
before it responds to il. By using such a procedure, you can modify the effect of an 
event any way you like. If you are not using a custom filter procedure (the usual 
case), just push a long word zero on the stack. This invokes the standard filter 
procedure which converts a press of the Return key to a mouse click in the box's 
default button; it also handles the keyboard commands lor cut (OponApple-X), copy 
(OpenApple-C), and paste (OpcnApple-Y) operations properly. 

A sample filter procedure is shown in listing 8-2. When ModalDialog calls it, 
there is a result space, three long values, and a three-byte return address on the 
stack; 

result (word) 

dialog pointer (long) 

pointer to event record (long) 

pointer to itemHit variable (long) 

return address (3 bytes) 

When the filter procedure ends, it must remove the three long input parameters 
from the stack by moving the return address up by 12 bytes and adjusting the stack 

pointer accordingly 

The result of a filter procedure is a Boolean value. If it is true, ModalDialog ends 
and returns the ID number which the filter procedure returns in itemHit. If it is 
false, ModalDialog handles the event in its usual way. 

The filter procedure can tell what type of event it is dealing with by checking 
the "what" field of the event record. To force the event to be ignored, it can put a 
in the What field to convert the event to a null event. 

The procedure in listing 8-2 filters out keyboard control characters (other than 
those needed for editing) in this way. Without this filter, control characters appear 
as inverse question marks in an EditLine item. 

When designing a custom filter procedure, you should strive to retain the be- 
havior of the default filter procedure. To do this, set the high-order bit of FilterProc'* 
address when you push it on the stack for ModalDialog. This tells ModalDialog to 
pass events to the standard filter after the custom filter procedure deals with them. 

When ModalDialog takes over, it handles any update events related to the dialog 
(caused when a control item like a button or a check box changes value.) and monitors 
all events until an active item is selected It beeps if the mouse is clicked outside 
the dialog window and ignores all clicks inside the window if they are not also inside 
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the display rectangle of an enabled item. Mouse-down events in control items, such 
as buttons, radio buttons, and check boxes. Lire monitored until the mouse is 
released; if the mouse is not still in the item upon release, the click is ignored. 

When ModalDialog finishes it returns the number of the item selected, The 
application can then deal with this result as it wishes; it can then either remove the 
dialog box from the screen or call ModalDialog once again. 

The action a program takes when ModalDialog returns a result depends on the 
type of item selected- If it was a cheek box, the box should be checked if it was 
previously unchecked or vice versa, If it was a radio button, the radio button should 
be selected and all other radio buttons in the group should be deselected. Standard 
subroutines For doing this are shown in listings H-3 and 8-4, 

When a button is selected, you should read and save the settings of the variable 
items in the dialog and then dismiss the dialog by removing its window from the 
screen with CloseDialog. 

Key-down events are processed by ModalDialog only if there is an EditLine item 
in the dialog. If the EditLine item is enabled, its item number is returned after 
every key press. If it is not, no item number is returned, but ModalDialog still lets 
von edit the string in the text box. It is probably best to disable EditLine items (by 
adding 8&000 to the item code in the item template) so that you do not have to 
keep looping back to ModalDialog after every key press. Instead, after a button is 
pressed to dismiss the dialog, you can use GetlTcxt to determine the final value of 
the text string. 

The Tab key is used to move the text insertion cursor from one EditLine item 
to the next. If you are in the last EditLine item when you press Tab, you will 
proceed to the first such item. 

Mouse-down activity in EditLine items is automatically handled by ModalDialog 
in accordance with the LineEdit specifications described earlier. In fact, Modal- 
Dialog calls LineEdit to handle these events. 

Modeless Dialog Boxes 

A modeless dialog box is a bit more difficult to handle than a modal dialog box. 
When a modeless dialog box is on the screen, the user is not restricted from 
performing other operations (such as activating another window or selecting a desk 
accessory) before dismissing it to remove it from the screen. In this respect, a 
modeless dialog box is like any other standard window, although it contains various 
controls, Unlike a modal dialog box or an alert box, it does not retain control until 
you select an active item. You simply feed it events one at a time and it returns a 
Boolean result that tells you whether the event related to the dialog box or not. 
To create a modeless dialog window, yon must use NewModelcssDialog as follows: 

PLA jspace for result (long) 

PLA 

PushPtr dBoundsRect ;Pointer to window rectangle 
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Figure 8-4, A Modeless Dialog Box 



Search for Text 



Modeless 



Begin Search 



PushPtr dTitle 
PushLong dBehind 

PushWord dFlag 
PushLong dRefCon 
PushPtr dFullSize 
_NewModel essDialog 
PapLong DialogPtr 



Pointer to dialog title 
Pointer to window in front 

of dialog window 
Window frame bit vector 
reference constant 
Pointer to- zoom rectangle 

ipop pointer to dialog 



Most i)l these parameters are self-explanatory, Normally, you set dBehind to -1 to 
bring the modeless dialog box up in front of all other windows. The dFlag vector 
has the same meaning as the window frame vector in a New Window call; most 
dialog windows have only a close box and a title area, 

The parameters passed to NewMoctelessDialog do not include the items to be 
drawn in the dialog window. You inusl add these by making calls to GetNewDltern 
or NewDItein 

The program in listing 8-5 shows how to define a modeless dialog box. The box 
it defines is shown in figure S— 4. 

The Dialog Manager makes it somewhat easier to deal with a modeless dialog 
box than a standard window. Whenever your program calls TaskMaster or Gel- 
NextEvent, it should call IsDiatogEvenl to determine whether the current event 
relates to the modeless dialog box (see the program in listing 8-6): 



PHA 

PushPtr EventRecord 

_ I sDia 1 ogEven t 

PLA 



■Space for Boolean result 
■, TastMaater/GetNextEven t recorc 

; Pap true/false result 
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The EventRecord is the one used with TaskMaster or GetNextEvent. Listing 8-6 
shows how to handle events in modeless dialog boxes. 

If the result is false, the event was not dialog-related and can be processed as 
usual. This includes events for which TaskMaster returns wlnMenuBar or win- 
Special, unless it was caused by a key-down event (that is, unless the user entered 
a keyboard equivalent). 

Special edit items Involving modeless dialog windows can be handled by calling 
a subroutine like the one in listing 8-7. In brief, it checks to see il the active window 
is the modeless dialog window; if it is, it handles the special edit item by calling 
one of the following functions: 

DlqCut Cut the selected text and put it on clipboard 

DlgCopy Copy the selected text to the clipboard 

DlqPaste Transfer the text on clipboard to the document 

DlgDelete Erase the selected text; clipboard not affected 

(There is no similar Inaction for handling the special Undo item. An applies 
should handle Undo by canceling the previous edit operation.) All these dialog 
editing functions require only one parameter, the handle to the dialog record. 
Is Dialog Event returns true for the following events; 

• Activate or update events for a dialog window 

• Mouse-down events in the content region of an active dialog window 

• Any other event when a dialog window is active 

When IsDialogEvent returns a true result, you normally call DialogSelect to process 
it. If you are using TaskMaster, however, you should cheek first to see il the 
TaskMaster result was wlnMenuBar or wlnSpecial, For either result, TaskMasU ir 
will have highlighted the menu title, so turn off highlighting with HiliteMenn (see 
chapter 7). DialogSelect does not do this for you. 

The wlnSpecial results should then be passed directly to DialogSelect for pro- 
cessing. If the modeless dialog box has an EditLme item, the Item will be edited 
accordingly. The wlnMenuBar results should be dealt with separately because 
DialogSelect will not know what to do with them. 

Here is how to call DialogSelect: 

PHA ;Space for Boolean result 

PushPtr EventRecord ; Taskmaster /Get NextEvent recor 

PushPtr theDialog -.Dialog pointer returned here 

PushPtr itemHit ' ; 1 tern number returned here 

.DialogSelect 

PLA ;Get true/false result 



RTS 
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itemHit DS 2 ; I tern number returned 

theDialog DS A '.Pointer to dialog record 

DialogSelect takes the event, processes it, and returns a Boolean result indicating 
whether it related to an enabled dialog item. If the result is false, it did not relate 
to an enabled item, and you do not have to do anything further. DialogSelect always 
returns a false value if you pass it a window update or activate event; these events 
are processed internally. 

If the result is true, the itemHit and theDialog variables will contain the number 
of the item selected and a pointer to the active dialog record. You can then deal 
with the result in the same way you deal with a result returned by a call to 
ModalDialog for a modal dialog box. DialogSelect always returns a true result in 
situations in which ModalDialog would have reported an item-related event to you. 

USING ALERT BOXES 

There are four Dialog Manager functions for displaying alert boxes on the screen: 

• Alert 

• Stop Alert 

• Note Alert 

• Caution Alert 



You call each of these functions in exactly the same way. The only differences among 
them are the icons they display in the top left corner of the box. Alert displays no 
icon at all; StopAlcrt displays an octagonal stop sign with a hand in it: NoteAlert 
displays a talking person, CautionAlert displays a yield sign with an exclamation 
mark in it- 

The program in listing 8-8 shows how to create and deal with an alert box. 

Alert boxes are easy to usc\ because all screen and event activities are handled 
by a single function. This function creates the alert record, draws the alert box and 
its items, interprets events until an active item in selected, erases the alert from the 
screen, and disposes of any memory used by the alert record. The function returns 
the item number selected. All you have to do is monitor this result and take whatever 
action is appropriate. Compare this with dialog boxes, which require you to use 
different functions to create and dispose of the dialog. 

To display an alert box, pass pointers to an alert template and a filter procedure 
to the function: 
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PHA -.space for result 

PushPtr A 1 er tTemp la te '.Pointer to alert template 

PushPtr FilterProc ;Pointer to filter procedure 

_Aler t 

PLA ; ID of item selected 

Alert handles mouse clicks much as ModalDialog handles them. That is. mouse 
clicks outside the alert box produce error beeps, and clicks in disabled items are 
ignored. Alert returns the value of any enabled item that is selected. For an alert 
box, only button items should be enabled. 

An alert template, like a dialog template, includes a list of items that are to 
appear in the alert box. Its exact structure is as follows: 

DC Mt,l,b t r' ;Alert bo* rectangle 

DC I'AlertID 1 J ID number for alert box 

DC Il'Stagel 1 -.First stage alert 

DC M'Stage?' .Second stage alert 

DC I1'5tage3' ; Third stage alert 

DC M'Stagel' -.Fourth stage alert 

DC M'lteml' ;Pointer to 1st item template 

DC I4'Item2' -.Pointer to 2nd item template 

DC M'ltemN 1 ;Pointer to Nth item template 
DC [4'Q 1 ;zero terminator 

The item templates referred to in an alert template are identical to the ones discussed 
earlier in connection with modal dialog boxes. 

Stage bytes make up an important parameter in an alert template. They define 
the behavior of the alert in each of four different stages. When yon use the alert 
box for the first time, it enters the first stage. As you keep calling it, it progresses 
through the second, third, and fourth stages, in that order. Thereafter, the alert box 
always behaves as if it was in the fourth stage. You can reset the alert stage to 
with ResetAlertStage (no parameters). 

As shown in figure 8-5, the characteristics associated with each stage are what 
the default button is to be, what sound is to be emitted, and whether the alert box 
is to be drawn. 

For a given stage, the first two bits (0 and 1) contain a sound number from to 
3. In most cases, this number represents the number ol times the speaker is to 
beep when an alert is called up at that stage level. It is possible, however, to invoke 
a custom sound procedure that interprets these numbers differently. Refer to the 
Apple IlGS Toolbox Reference for instructions on how to do this. 

Bit 7 indicates whether the alert box is to be drawn on the screen. You will 
usually set this bit to 1 (display the box), but you can set it to if you do not want 
the alert to be displayed at that stage level. 

Bit 6 controls which of two buttons is to be the default button. The default button 
is the one selected when Return is pressed from the keyboard. If the bit is set to 
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Figure 8-5. The Format of a Stage Byte in an Alert Template 



7 


6 


5 


4 


S 


2 


1 






not used 



sound number (0 to 3) 

_ ID of default button 
minus 1 

1 = draw alert box 
= don't draw box 



0, the first button (usually an OK button] is the default; if it is 1, the second button 

(usually u Cancel button) is the default 

In most applications you will probably want all stages to he equivalent, so all four 
bytes will be the same. For example, if you want to beep the speaker once, display 
the alert box, and make the Cancel hut ton the default button, use a stage byte of 
SCI. This sets the sound number In 01 (one beep), sets bit 7 to 1 {draw the box), 
and sets bit 6 to I (the default is #2, Cancel). 

The filter procedure used by an alert box is similar to the one described earlier 
for dialog boxes. Pushing a value tells the function to use the standard filter 
procedure It converts a Return keypress into the click of the default button in the 
alert lm\ 



REFERENCE SECTION 

Table R8-1j The Major Functions in the Dialog Manager Tool Set (jig 



Function Stinw 



Alert 



Function Stack 

V 1 1 nihc r Fa rametc rs 



SIT 



ription of 
Parameter 



result (W) ID of item selected 

AlerfTemp (L) Ptr to alert template 

FilterProc 1 1- Fir to filter procedure 



290 f sing Dialog and Alert Boxes 





Function 


Stack 


Description of 


Function Same 


Number 


Parameters 


Parameter 


Cant ion Alert 


SIA 


result iWi 


ID ol Item selected 






AlertTernp (L] 


Ptr to alert template 






FilterProc (L) 


Ptr to filter procedure 


CloseDtalog 


$0C 


TheDialog 1. 


Ptr to dialog record 


DialogSelei 1 


$11 


result \V 


Boolean: enabled item 
chosen? 






EventRecord (L) 


Ptr to event record 






TheDialog (L) 


Ptr to space for dialog ptr 






IteinHitPlr (L) 


Ptr to space for item number 


Dialogs hut Down 


$03 


I tin parameters] 




Dialogs tart up 


$02 


UserlD M 


ID tag for memory allocation 


Disable!.) Item 


539 


TheDialog (L) 


Ptr to dialog record 






ItemID (W) 


ID of item to disable 


DlgCut 


$12 


The Dial. 


Ptr to dialog record 


DlgCopy 


$13 


TheDialog (L) 


Ptr to dialog record 


DlgDeletc 


$15 


TheDialog iL: 


Ptr to dialog record 


DlgPaste 


$14 


TheDialog (L) 


Ptr to dialog record 


EiiableDItern 


$3A 


TheDialog (L) 


Ptr to dialog record 






ItemID iAVi 


ID of item to enable 


Find D Item 


S24 


result fW) 


ID of item at point 






TheDialog (L) 


Ptr to dialog record 






HieFoint L: 


Point to cheek (global) 


GetDefButton 


$37 


result i\V"i 


ID of default item 






TheDialog 1 LJ 


Ptr to dialog record 
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Function 


Stack 


Description of 


Function Same 


Number 


Parameters 


Parameter 


Gel U Item Box 


$28 


TheDialog (L) 


Ptr to dialog record 






ItemID (W) 


ID of dialog item 






ItemBovPtr (L) 


Ptr to returned rectangle 


GetDItemType 


$26 


result (W) 


[tem type code 






TheDialog (L.) 


Ptr to dialog record 






ItemID (W 


ID of dialog Item 


Get D I rem Value 


82 E 


resull iw;i 


Value of dialog item 






TheDialog (L) 


Ptr to dialog record 






ItemID (W) 


ID of dialog item 


GetlText 


S1F 


TheDialog (L) 


Ptr to dialog record 






ItemID iWj 


ID of dialog item 






TheString (L) 


Ptr to result string space 


GetNewDItem 


S33 


TheDialog (L) 


Ptr to dialog record 






ItemTemp (L) 


Ptr to item template space 


GetNewModalDisdog 


S32 


result (L) 


Ptr to dialog record 






DialogTemp (L) 


Ptr to dialog template 


HideDItera 


$22 


TheDialog (L) 


Ptr to dialog record 






ItemID (W) 


ID of dialog item 


IsDialogEvent 


$10 


result (W) 


B< :>■ ) K ; ii i . dialog-related f 1 






Event Record (L) 


Ptr to event record 


Modal Dialog 


80F 


result (W) 


ID of selected item 






FilterFroc (L) 


Ptr to filter procedure 


NewDltcm 


$0D 


TheDialog (L) 


Ptr to dialog record 






ItemID (W) 


Item ID number 






HemRect (L) 


Ptr to item rectangle 






Item-Type (W) 


Item type code 






ItcmDescr (L) 


Item descriptor 
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Function 


Stack 


Description of 


Function Name 


Number 


Parameters 


Parameter 






ItcmValue (W) 


Item value 






Item Flag (VV) 


Item flags 






ItemColorPtr (L) 


Ptr to item color table 


N ew M odal Di alog 


$0A 


result (L) 


Ptr to dialog record 






DBoundsRect (L) 


Ptr to dialog rectangle 






DVisible (W) 


Boolean: is it visible? 






DRetfGon (L) 


Reference constant 


NewModelessDialog 


$0B 


result (L) 


Ptr to dialog record 






DBoundsRect (L) 


Ptr to window rectangle 






DTitlcPtr (L) 


Ptr to dialog title 






DBt bindPtr (L) 


Ptr to window in front 






DFlag (W) 


Window frame bit vector 






DRefCon (L) 


Reference constant 






DFullSizePtr (L) 


Ptr to zoom rectangle 


NoteAlcrt 


$19 


result (W) 


ID of item selected 






AlertTemp (L) 


Ptr to alert template 






FilterProc (L) 


Ptr to filter procedure 


ParamText 


$1B 


ParamOPtr (L) 


Ptr to *0 string 






ParamlPtr (L) 


Ptr to "1 string 






Param2Ptr (L) 


Ptr to *2 string 






Param3Ptr (L) 


Ptr to '3 string 


SellText 


$21 


TheDialog (L) 


Ptr to dialog record 






itemID (W) 


ID of dialog item 






SlartSel (W) 


Start of selection range 






EndSel (W) 


End of selection range 


SetDcfButton 


$38 


TheDialog (L) 


Ptr to dialog record 






DeffiutlD(W) 


ID of new default button 
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Function 


Stack 


Description of 


Function Name 


Number 


Parameters 


Parameter 


SetDItemBos 


$29 


TheDialog (L) 


Ptr tt) dialog record 






ItemID (W) 


ID of dialog item 






ItemBoxPtr <L) 


Ptr to new rectangle 


SetDIteraType 


$27 


ItemType (W) 


New item type code 






TheDialog (L) 


Ptr to dialog record 






ItemID (W) 


ID of dialog item 


SetDItem Value 


$2F 


ItemValue (W) 


New value for item 






The Dialog (L) 


Ptr to dialog record 






ItemID (W) 


ID of dialog item 


Set [Text 


820 


TheDialog (L) 


Ptr to dialog record 






ItemID (W) 


ID of dialog item 






TheString (L) 


Ptr lo new text string 


ShowDltem 




TheDialog (L) 


Ptr to dialog record 






ItemID (W) 


ID of dialog item 


StopAlert 


$18 


result (W) 


ID of item selected 






AlertTemp (L) 


Ptr to alert template 






FilterProc (L! 


Ptr to filler procedure 



Table R8-2: Dialog Manager Error Codes 



Error 




Code 


Description oj Error Condition 


S150A 


The item type code is invalid. 


$150B 


The Newltem call was unsuccessful. 


$150C 


The specified item was not found. 


$150D 


The active window is not a modal dialog box. 
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Table RS-3: U 


st'ful Functions 


in the LineEdit Tool Set ($14) 


Function Name 


Function 

X umber 


Shick 
Parameters 


Description cf 
Parameter 


LE Shut Down 
LEStiirkip 


$03 

$02 


| mi parameters) 

UserlDfW) 

DPAddr(Vt 


113 tap; tor memory allocation 
Address of 1 page in bank 
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Listing 8-1: Defining and Handling a Modal Dialog Box 

Modal START 

Using DlogData 

; Create the modal dialog box: 





PHA 
PHA 

PushPtr DialogBox 
_Ge tNewModalDia 1 og 
PopLong TheDialog 


GoModal 


PHA 

PushLong *0 
.ModalDialog 
PLA 




CMP #1 

BEQ GoModaH 



; Space for result 



;5pace for result 
; standard filter procedure 
j Handle activity in box 
;Get the item selected 



;QK button' 

•, Yes , so branch 



CMP #20 

BCC Toggle 



^Checkbox"? 

; Yes, so branch 



; If we reach here, it must be a radio button. 

; When you turn one radio button on, all other family 
; members are turned off automatically; 



GoModal! 



TAX 

PushWord *\ 

PushLong TheDialog 

PHX 

_Set ItemValue 

JMP GoModal 

ANOP 



;Turn selected radio button on 

-,Push selected item 

; Redraw with new value 
;Go back to dialog 



Here is where you would inspect and save the settings of 
all the variable parameters so thai you ean use them in 
another part of the program. Use Get I temValue and GetlText 
to determine the value for each item. 



PushLong TheDialog 

_CloseDialog 

RTS 



; Ge t rid of dialog 
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5 Toggle the setting of the check box: 

Toggle ANQP 

TAX 

PHX iSave ID 

PHA ;Space for result 

PushLong TheDialog 

PHX ;Push item ID 

_Get I temVa lue 

PLA ;Get current value 

EDR #101 ;Toggle value bit 

PLX ;Get ID back 

PHA ;New value 

PushLong TheDialog 

PHX 

_Set I temVa lue jredraw with new value 

JNP GoModal -.Back to dialog 

END 

DlogData DATA 
TheDialog DS 4 

; Di a log Templa t e : 



Dial ogBox 


DC 


I '30,100 J 35, 465' 






DC 


I '*FFFF' 


; True ■ visible 




DC 


1 4 ' ' 


; ref con 




DC 


I4'DItem1 • 






DC 


M'DItem2' 






DC 


I4'DItem3' 






DC 


I4«DItem4' 






DC 


M'D ItemS' 






DC 


t4^D[tem6 , 






DC 


H'DI tern?" 






DC 


14 • D I temS' 






DC 


14 'DI teraS ' 






DC 


I4'DI teml f 






DC 


[4'Dltem1 1 • 






DC 


l4'DItem1S' 






DC 


14'DIteml 3* 






DC 


l4'DItem14' 






DC 


H'DItemlS' 






DC 


I4'DI temlG' 






DC 


I4'DItem17< 






DC 


14 'DltemlB' 
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DC 


I4'D1 tem19' 




DC 


I 4 » Dl tem20 ' 




DC 


I4'DItem21 ' 




DC 


I 4 • • 


Dlteml 


DC 


I2'1 ' 




DC 


I2'80 t 300,100,360' 




DC 


I2'ButtonI tem 1 




DC 


I4'ButtonStr ' 




DC 


I 2 ' ' 




DC 


I2'0« 




DC 


14*0' 



Item ID (1 ■ default button) 

Display rectangle (local) 

Item type code 

Name of button 

Not used 

[tem flag (default) 

Color table ptr (default) 



ButtonStr STR 



'OK' 



Dltem2 


DC 


I 2 ' 2 * 




DC 


IZ'S^O.M.SOO' 




DC 


l2'StatText+*BQ00 




DC 


I4'Stat1 ■ 




DC 


I 2 ' ' 




DC 


12'0' 




DC 


I 4 » ■ 



Item ID 

Display rectangle (local] 

Item type code (disabled) 

Static text string 

Item value (unused) 

Item flag (default) 

Color table ptr (default) 



Stall 



STR 



'Communications Parameters' 



^Static text string 



DI tem3 


DC 


I2'3' 




DC 


12 M 7,10,27 J 00' 




DC 


I2 ( StatTe)tt*tBO00« 




DC 


I4'5tat2' 




DC 


[gtQi 




DC 


12'Q* 




DC 


I 4 ■ « 



Item ID 

Display rectangle (local) 

Item type code (disabled) 

Static text string 

Item value (unused) 

Item flag (default) 

Color table ptr (default) 



Stat2 



STR 



'Baud Rate: ' 



;Static text string 



DItem4 


DC 


1 2 ' 4 ' 




DC 


12' } 7, 1 00 ,27,180 




DC 


12'RadioItem' 




DC 


14 'Radiol ' 




DC 


I2'0» 




DC 


I2'1 » 




DC 


I4'0' 



Item ID 

Display rectangle (local) 

I t em t ype code 

Name of button 

Value: = off / 1 ■ on 

Baud rate family 

Color table ptr (default) 



Radiol 



5TR 



' 300' 



DItemS DC 

DC 
DC 
DC 



i2<5' 

12' 1 7,180,27,260' 

12'Radioltem' 

!4'Radio2' 



Item ID 

Display rectangle 
Item type code 
Name of button 



1 oca J 
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DC 


I2'1 ■ 




DC 


I2M « 




DC 


I 4 » ' 


Radio? 


STR 


M200" 


DItemG 


DC 


I2»G« 




DC 


IZM7, 260,27,340" 




DC 


12'RadioI tern' 




DC 


I4'Radio3' 




DC 


I2«0" 




DC 


I2M ' 




DC 


I 4 • ' 


Radio3 


STR 


'2400' 


DIlem7 


DC 


I2»7« 




DC 


]2'29, 10,39,100' 




DC 


I2«StatText*S8QQ0' 




DC 


14'Stat3» 




DC 


12 • ' 




DC 


I2'0' 




DC 


H'O' 


Stat3 


STR 


'Data Bits: ' 


DllemS 


DC 


12*8' 




DC 


I 2' 29 ,100 ,39, 150' 




DC 


12'Radio! tem' 




DC 


I4'Radio4' 




DC 


12' 1 ' 




DC 


12'2' 




DC 


14<0 f 


Radio4 


STR 


•8' 


DItem9 


DC 


12 r 9' 




DC 


12 ■ 29, 150,39,20 0' 




DC 


12tRadiol tern' 




DC 


J4'Radio5' 




DC 


I 2 * ' 




DC 


I2t2* 




DC 


1 4 • * 


Radi oS 


STR 


'7' 


DItemlQ 


DC 


12M0' 




DC 


12 f 41 , 10, SI ,1 00 ' 




DC 


12'StatText+S80QG' 




DC 


!4*Stat4« 




DC 


12M ' 



iValue: = off / 1 ■ on 

; Baud rate f ami ly 

; Col or table ptr (default) 



; 1 1 em ID 

■Display rectangle (local) 

\ 1 I em type code 

•.Name of button 

;Value: « off / 1 ■ on 

•.Baud rate f ami Ly 

; Color table ptr (default) 



Item ID 

Display rectangle (local) 
Item type code (disabled) 
Static text string 
Item value (unused) 
I tem flag (def aul t ) 
Color table ptr (default ) 

Static text string 

Item ID 

Display rectangle (local) 

I tem type code 

Name of button 

Value: = off / 1 = on 

Data bits family 

Color table ptr (default) 



Item ID 

Display rectangle (local) 

1 t em type code 

Name of button 

Value: - off / 1 ■ on 

Data bi t 5 f ami ly 

Color table ptr (default) 



Item ID 

Display rectangle (local] 
Item type code (disabled] 
Static text string 
Item value (unused) 
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DC 


I 2 • ' 




DC 


I 4 ' « 


Stat4 


STR 


1 Stop Bits;' 


Dltemll 


DC 


I2M1 ' 




DC 


I2'41 ,100,51 ,150' 




DC 


12'Radioltem' 




DC 


M 'RodioB' 




DC 


I2'1 ' 




DC 


12*3' 




DC 


I4'Q' 


Radio6 


STR 


M ' 


DItem12 


DC 


I2'12' 




DC 


1 2' 41 ,150,51 ,200' 




DC 


12'Radioltem' 




DC 


I 4 • Radi o7 ' 




DC 


I 2 • • 




DC 


I2'3« 




DC 


I 4 • ' 


Radio7 


STR 


'2' 


Dltem13 


DC 


I2M3' 




DC 


I2'53,10, 63,100' 




DC 


I2'StatText+*BQO0 




DC 


I4'Stal5' 




DC 


I2M ' 




DC 


12*0' 




DC 


I4»0» 


StatS 


STR 


'Parity: ' 


DItem14 


DC 


I2M4' 




DC 


I2'53 J00, 63,180' 




DC 


12 ' Radiol tern 1 




DC 


14'Radio8' 




DC 


12M ' 




DC 


I2'4' 




DC 


14'0' 


RadioS 


STR 


■Mesne' 


DI tem15 


DC 


12*15' 




DC 


12*53,180,63,260' 




DC 


12'Radioltem' 




DC 


14'RadioS' 




DC 


I 2 * f 



■, I tem flag (def aul t ) 
{Color table ptr {default ) 

;5tatic text string 

j Item ID 

Display rectangle (local) 

I tem type code 

Name of button 

Value: ■ off / 1 = on 

Stop bits family 

Color table ptr (default) 



Item ID 

Display rectangle (local) 

I tem type code 

Name of button 

Value: * off / 1 = on 

Stop bits f ami ly 

Color table ptr (default) 



{Item ID 

[Display rectangle (local) 
; 1 1 em type code (disabled) 
; St a t ic text s tri ng 
;Item value (unused) 
litem flag ( def aul t ) 
'.Color table ptr (default) 

{Static text string 

; I tem ID 

-.Display rectangle (local) 

; 1 1 em type code 

".Name of button 

{Value; - off I \ = on 

;Par i ty f ami ly 

{Color table ptr (default) 



; Item ID 

{Display rectangle (local) 

; 1 1 em type c ode 

; Name of button 

-.Value: ■ off / 1 = on 
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DC 


I2'4' 




DC 


14' 0' 


Radio9 


STR 


1 Even ' 


Dltem16 


DC 


12 I 16' 




DC 


12 '53,260 ,63,340' 




DC 


12'Radioltem r 




DC 


14 'Radiol ' 




DC 


12«0i 




DC 


I2'4» 




DC 


I4'0« 


Radiol 


STR 


'Odd' 


Dlteml 7 


DC 


1 2 • 1 7 ' 




DC 


12'6S, 10, 75,120' 




DC 


12'CheckI tern' 




DC 


l4'Check1 ' 




DC 


12' 0' 




DC 


12'Q 1 




DC 


I 4 ' ' 


Checkl 


STR 


'Filter' 


DItemIS 


DC 


12' 18' 




DC 


12'65,120, 75,230' 




DC 


I2 ( CheckItem' 




DC 


I4'Check2 1 




DC 


1 2 M i 




DC 


I2'0' 




DC 


I4'0' 


Check2 


STR 


'XON/XOFF' 


Dl teml9 


DC 


I2'19< 




DC 


I 2' 65 ,230 ,75 ,340' 




DC 


12'ChecfcI tern' 




DC 


I4'Check3' 




DC 


I 2 • 1 




DC 


12'Q 1 




DC 


I4'D' 


Check3 


STR 


' L i ne De lay 1 


DItemao 


DC 


1 2 ' 20 ' 




DC 


1 2 ' 79 , 1 , 89 , 1 1 5 ' 




DC 


12' 5tatText+»SQQ0 




DC 


M'StatfcV 



[Parity family 

;Color table ptr {default 



Item ID 

Display rectangle (local' 

1 tern type code 

Name of button 

Value: = off / 1 ■ on 

Par i t y f ami ly 

Color table ptr (default! 



Item ID 

Display rectangle (local) 

Item type code (disabled) 

5tatic text string 

Value: ■ off / 1 ■ on 

I tern flag (default ) 

Color table ptr (default) 



Item ED 

Display rectangle (local) 
Item type cade (disabled) 
Static text string 
Value: - off / 1 = on 
I tern f lag (def aul t ) 
Color table ptr (default) 



Item ID 

Display rectangle (local) 
Item type code (disabled) 
Static text string 
Value: * off / 1 = on 
I tern f lag ( def au 1 1 ) 
Color table ptr (default) 



Item ID 

Display rectangle (local) 
Item type code (disabled) 
Static text string 



Reference Section 301 



DC 


1 2 ' ' 


::c 


T2 ' ' 


DC 


M'O ' 



; I tern ualue (unused) 
-, J tem flag (default ) 
;Color table ptr (default) 

State STR 'Download File;' {Static text string 

DItem21 DC 12'21 ' !*te» ID 

DC I2'77,12Q,90 ,275' -.Display rectangle (local) 

DC 12'EditLine+iBOOO' ; Item type code (disabled) 

DC 14'EditString 1 ;Editable text string 

DC 12*15' ;Maximum string length 

DC 1 2 * Q • litem flag (default) 

DC !4'0' ;Color table ptr (default) 

EditString STR 'Messages' 

END 

Listing 8-2: A Filter Procedure for ModalDiaioR __^__ 



This is a custom filter procedure for ModalDiaiog. 
Dn entry, the stack is configured as follows: 



resul t : 


WORD 


theDia 1 og : 


LONG 


theEvent : 


LONG 


1 1 emH 1 1 : 


LONG 


retur nAddr : 


3 BYTES 



Return a TRUE result if ModalDiaiog is to exit with it emH it 
or a FALSE result if it is to process the event itself. 

To use a fitter procedure, pass a pointer to it to ModalDiaiog. 
Set the high bit of the pointer to daisy chain to the standard 
filter which handles keyboard editing commands and converts a 
Return press to a click of the default button, Here's how to 
do this : 

PHA 

LDA #*FilterProc ;Address high 

ORA #18000 ;Set high bit 

PHA 

LDA #FilterProc ;Address low 

PHA 

_Moda lDi a I og 

This particular filter effectively removes all non-editing 
control characters so they won't appear as inverse question 
marks in an EditLine item. 
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FilterProc START 

j these are direct page addresses after PHD/TSC/TCDs 

QldDB EQU tO 1 

DldDP EQU OldDB+1 

ReturnAddr EQU QldDP*2 

ItemHit EQU ReturnAddr*3 

theEvent EQU itemHit*4 

theDialag EQU theEvent+4 

result EQU theDialog+4 

PHB ;Save data bank register 

■HJiow absolute addressing 

;5ave direct page 
;Align d.p. with stack 

; Get "what 11 from event record 
;Key down event' 
;No, so branch 

;Oet ASCI ! code 
;Convert to std ASCI 1 
;Control character? 
;No, so branch 

jFllter all control chars, except CR or ones used by LineEdlt: 

LDX 

CtrlLook CMP CtrlTable,X ;1s it in the list? 

BEQ Exit ;Yes, so branch 

INX ;Move to next entry 

INX 

CPX TblSize ;At end of table? 

BNE CtrlLook ?No, so branch 



PHK 




PLB 




PHD 




TSC 




TCD 




LDA 


[theEvent ] 


CMP 


#3 


BNE 


Exit 


LDY 


'2 


LDA 


[theEvent J ,Y 


AND 


#SQ07F 


CMP 


#10020 


BCS 


Exit 



*0 




CtrlTable, 


:■: 


Exit 




TblSize 




CtrlLook 




#0 




t theEvent) 




#0 




r e s u I t 





LDA #0 ; Convert to "null" event 

STA 

Exit LDA #0 -.False result 

Exit! STA 

PLD ^Restore d.p. 

PLB ^Restore data bank 
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* Discard input parameters and move stack up by 12 bytes: 



LDA 


2,5 


STA 


14,S 


LDA 


1,5 


STA 


13, S 


TSC 




CLC 




ADC 


#12 


TCS 





RTL 



; This table contains all the control characters 
; that are specially treated by LineEdit, and CR. 



Ctrl Table 


DC 


»$G6' 




DC 


' 108' 




DC 


<»09' 




DC 


"SOD 1 




DC 


'•15' 




DC 


'$18' 




DC 


'119' 


TblSize 


DC 


•TblS 



TblSize-CtrlTabie' 



;Delete char below cursor 

jLeft-arrow (backspace) 

;Tab 

;CR 

; Right -arrow (■forward) 

jControl-X (erase line) 

;Control-Y (clear to EOL) 



END 

Listing 8-3: The CheckHit Subroutine to be Called When ModalDialog Returns 
a Check Box Hem 

Call CheckHit in response to a hit in a dialog 
check box. CheckHit changes the value of the 
item from to 1 (if it is off) or from 1 to 
(if .it is on ) . 

On entry, A contains the ID number of the 
check box item in question. 

TheDialog 15 a dialog pointer stored in 
the GlobalData data segment, 

CheckHit START 

Using GlobalData 



TAX 
PHX 



;Save 1] 
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PHA ;Space for result 

PushLonq TheDialog 

PHX ;Push item ID 

_Get I temValue 

PLA 



EQR '$01 slnvert value bit 



PLX ; Get ID back 

PHA ;New value 

PushLong TheDialog 

PHX 

_Set 1 temValue ".redraw with new value 

RTS 



END 



Listing 8—4: The RadioHit Subroutine* to be Called When Modal Dialog Returns 
a Radio Button Item 

Call RadioHit in response to a hit in a dialog 
radio button, RadioHit sets the value of the 
item to 1. This causes all other family members 
to be turned of f . 

On entry, A contains the ID number of the 
radio button item in question. 

TheDialog is a dialog pointer stored in 
the GlobalData data segment. 



RadioHit START 

Using GlobalData 



TAX ;Save item ID in X 

PushWord #1 ; 1 ■ on 

PushLong TheDialog 

PHX -,Pu5h item ID 

_Se t I t emVa 1 ue ;redraw with new value 

RTS 



END 



Reference Section 305 



Listing &-5: How To Creak- a Modeless Dialog Box 



; Create a modeless dialog box: 



ModeLess 



START 

Using DlogData 



PHA 

PHA 

Pus 

Pus 

Pus 

Pus 

Pus 

Pus 

_N 

Pop 



*,Spaoe for result 



hPtr DialogRect ^Content rectangle 

hPtr DlogTitle {Title of window 

hLong #-1 ;Ptr to window in front (-1 = top) 

hWord *X1 1 00000010100000 jframe: close, title, drag, visibl 

hLong *0 ;refcon 

hLong #0 ;zoofli rectangle (Q a default} 

wflodelesaDialog 

Long TheDialog 



PuihLong TheDialog 
PushPtf Dlteml 
_GetNewDI tem 

PushLang TheDialog 
PushPtr D!tem2 
_GetNewDl tem 
RTS 

END 



DlogData DATA 

DialogRect DC 

DlogTitle 5TR 



Dlteml DC 
DC 
DC 
DC 

DC 

DC 



ButtonStr STR 



Dl tem2 



DC 
DC 
DC 
DC 



I '30,60,100,425' 
f 5ear ch for Text 



TheDialog D5 4 
', Dialog Template: 



-, 1 1 1 1 e 
• t Pointer to modeless dialog 



I2M I 

12 • 40 , 110,60, 250' 

I2'Buttonltem' 

H'ButtonStr' 

1 2 ' ' 

12'0» 

I4'0' 

' Beq i n Search ' 



•,Item ID {1 £ default button] 

^Display rectangle (local) 
; I tem type code 
; Name of button 
;Not used 

; 1 tem f lag (def aul t } 
;Color table ptr (default) 



I 2 ' 2 ' ; 1 1 em I D 

I 2 • 1 7 , 1 00 ,30,320' ^Display rectangle (local) 
I2'Edi tLine*S8Q00" ; Item type code (disabled) 
14'EditString" -.Editable text string 



DC 12*20 ' ^Maximum string length 

DC 12*0' ; Item flag (default) 

DC ]4'0' ;Color table ptr (default] 

EditString STR " ;Start with null string 

END 

Listing 8-6: How To Handle Events in Modeless Dialog Boxes 



; Use this type of event loop when a modeless 
; dialog may be active. 

EvtLoop START 

Using Dl ogDa ta 

PHA 

PushWord #*FFFF ;A11 events 

PushPtr TaskRec 
_Task Master 

PHA ;apace for result 

PushPtr TaskRec 

_IsDial ogEvent ;ls it for modeless dialog 7 

PLA ;Get Boolean 

BEQ EvtLaopI iNo, so branch 

; If the keypress was a menu item keyboard equivalent, turn the 
; menu highlighting off. DialogSelect doesn't do this for you. 

', Get the Taskmaster result 
;Standard menu item? 
;Ye5, so fix menu title 
;Special menu item? 
; No, so do nothing 

; Highlighting off 
■, Get menu ID 



;Get menu item ID 

;Special editing item? 

*,Yes, so give It to DialogSelect 

; Handle non-editing keyboard equivalents here, 
; then return to the event loop. 

BRL EvtLoop 

DoModeless PHA ;space for Boolean result 

PushPtr TasfcRec ;Task record pointer 
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PLA 






CMP 


*wl nMenuBa r 




BEQ 


TitleQff 




CMP 


*wl nSpecia 1 




BNE 


DoModeless 


TitleQff 


Pu ahUor 


d #0 




PushWor 


d TaskData+2 




_Hi 1 i te 


Menu 




LDA 


TaskDa ta 




CMP 


#256 




BCC 


DoMode less 



PushPtr Dlog Active ; Dialog pointer returned here 

PuahPtr ItemHit ; Item number returned here 

_Dial ogSel ect 

PLA ;Was it handled'' 

BEQ EvtLoop ;No, so branch 

; The event is dialog-related if we reach here. DoDialog is a 

; subroutine you would write to handle dialog activity. It can 

; get the relevant dialog pointer from DlogActive and the item 

; number from ItemHit. 

JSR DoDialog ; Handle dialog activity 

BRL EvtLoop 

EvtLoopI PLA ;Get TaskMaster result 

1 [handle TaskMaster result in usual way] 

BRL EvtLoop ;Back to event loop 

DoDialog AHQP 

; [this subroutine handles dialog selections] 

RTS 





END 




Dl ogData 


DATA 




DlogAc t lve 


DS 


A 


ItemHit 


DS 


2 


EventRec 


ANOP 




What 


DS 


2 


Message 


DS 


4 


When 


DS 


A 


Wher e 


DS 


4 


Modi f ier s 


DS 


2 


TaskData 


DS 


4 


Tas kMask 


DC 


M ' 400001 FFF 



; Event record 
{Event code 

;Event result 
■/Ticks since startup 
vMouse location (global) 
•„Status of modifier keys 
; Task Master data 
;TaskMaster handles all 



END 



Listing 8—7: The Type of Subroutine a Program Should Call To Handle Editing 
When a Modeless Dialog Box is Active 

This subroutine handles special edit items for 
modeless dialog boxes. If the carry flag is set on 
exit, the edit command was handled. 

The pointer to the dialog is stored at TheDiatog. 
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DoEditing ANDP 

j Check to see if the modeless dialog box is active: 

PHA 

PHA 

_FrontWi ndow ;Get pointer to active window 

PLA 

PLX ^Compare active window with 

CMP TheDialog ; dialog window. 

BNE NoDlogEdit 

CPX TheDialog*2 

BNE NoDlogEdit 

;Pass control to the appropriate edit item handler: 

jGet menu ID 

^Convert 250-254 to 0-4 

;x2 to step into t*ble 





SEC 






LDA 


TaskData 




SBC 


#250 




ASL 


A 




TAX 






JSR 


(EditTabl 




SEC 






RTS 




NoDlogEdit 


CLC 
RTS 




EditTable 


DC 


1 *DUndo' 




DC 


1 r DCut ' 




DC 


1 'DCopy' 




DC 


1 'DPasle' 




DC 


I 'DClear • 


DUndo 


RTS 




DC ut 


PushLon 


a TheDialc 



; SEC means "was handled" 
;CLC means "not for dialog" 



; item 250 (Undo) 

;item 251 (Cut) 

l item 252 (Copy) 

litem 253 (Paste) 

;item 254 (Clear) 

;(there is no standard undo) 



_DlgCut 
RTS 

DCopy PuahLong TheDialog 
_DlgCopy 
RTS 

DPaste PushLong TheDialog 
_DlgPaste 
RTS 

DClear PushLong TheDialog 
_DlgDelete 
RTS 
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Listing 8-8; Defining and Handling an Alert Box 



i Bring up the alert box and watt for a button push: 

)oAlert START 

Using AlertData 



PHA 

PusbPtr AiertBox 

PushLong #0 

,Alert 

PLA 

RTS 



; space for result 
;0=default filter procedure 
;Oet item ID 



AlertData DATA 

; Alert box templet i 



AiertBox 



DC 
DC 

DC 

DC 
DC 
DC 
DC 



Alertltem! DC 
DC 

DC 
DC 
DC 
DC 
DC 



I 'GO ,70 , 1 20 t 400 ' ;Alert rectangle 



OKText 



STR 



1 '1 ' 

14'IC3C2C1CQ' 
14'Alert Iteml ' 
14' Alert Item2' 
I4»AlerWtem3 f 
I4«0« 

i 2 M ' 

I2'3Q,80 ,50,140' 

12 ' But ton I tern' 

14'OKText' 

12'0« 

I2'0' 

I 4 » • 

'OK' 



;Alert ID 
;Stages bytes 
;Pointer to item #1 
;Pcinter to item *2 
; Pointer to item #3 
\ Terminator 

1 Item ID 

'.Display rectangle (local) 

1 I tern type code 

;Name of button 

; 1 tern va lue ( of f ) 

; I ten flag (default ) 

-.Color table ptr (default) 



Alert Item2 DC 
DC 
DC 
DC 
DC 
DC 
DC 

CancelText STR 

Alert I tem3 DC 
DC 
DC 
DC 
DC 
DC 
DC 



12 r 2' ;1 tern ID 

I2'3Q, 180, 50,240' {Display rectangle (local 

I 2 ' ButtonI tern 1 ; I tern type code 

I 4 ' CancelText • jName of button 

I 2 ■ ' ; Item value (off) 

I 2 * • ; Item flag (default) 

I4'0' ;Color table ptr (default) 

'Cancel ' 

I2'3' 

I2M0, 80,22, 320' 

I2»StatT«xt*«8000 

14'StatString' 

12 ' « 

I2'0' 

I 4 ' « 



Item ID 

Display rectangle (local) 

-.Item type code (disabled) 
Stat ic text string 
Item value (unused) 
Mem flag (default) 
Color table ptr (default) 

'0 is a placeholder for a filename (Use ParamText to fill it In) 



StatString STR 

E •• P 



'Do you want to erase *Q?» -.Static text string 
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CHAPTER 9 



All about Desk 
Accessories 



Desk accessories are programs (usually small utilities) that reside in memory at the 
same time as a primary GS application. If the application is properly designed, a 
user can caJl up a desk accessory at any time, use it, return to the application, and 
continue on as if the application had never been interrupted. It is not necessary to 
restart the application from the beginning. 

Popular desk accessories are programs that provide features that few applications 
support directly: a calculator, note pad, clock, and appointment calendar, for ex- 
ample. 

The GS supports two types of desk accessories: classic desk accessories (CDAs) 
and new disk accessories (NDAs). As will be discussed, CDAs are available to any 
application hut NDAs work only with applications which take advantage of the 
desktop environment.. 

To call up a CDA. press three keys on the keyboard simultaneously — Control- 
OpenApple-Esc. This causes an interrupt signal, which the GS services by clearing 
the text screen and displaying a menu containing a list of the names of up to fourteen 
CDAs to choose from. You can activate a specific CDA by using the arrow keys to 
highlight the CDA name and then pressing Return. There are two standard CDAs 
in ROM: the Control Panel (used to configure the system hardware and set pref- 
erences) and the Alternate Display Mode {used to enable or disable software shad- 
owing of the secondary test screen from 8S0O to $BFF). 

You can access the CDA menu any time 65816 interrupts are not disabled (with 
an SEI instruction), which is most of the time. Thus. CDAs can be used with any 
CS application, including traditional lie-style applications and the new-style appli- 
cations that work in the desktop environment. 

NDAs, on the other hand, are available only to applications that use the desktop 
environment supported by the CS tools. This is because an NDA is called up by 
pulling down an "Apple " menu in the menu bar (created by the Menu Manager) 
and selecting the NDAs name. Most NDAs create windows that may coexist on the 
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screen with windows created by the application; the user can switch between desk 
accessory windows (also called system windows'* and application windows in the 
usual way — by clicking in the window to be activated. 

The purpose of this chapter is to show how to write programs which will work 
properly with desk accessories and how to write desk accessory programs them- 
selves. This involves a study of a tool set called the Desk .Manager (tool set 5). 

Before specifics are discussed, a preliminary word about the Desk Manager is 
appropriate. To start it up so that you can use desk accessories, call the DcskStartup 
Junction. Shut it down with the DeskShutDown function. Neither Function requires 
parameters nor generates results. 

CLASSIC DESK ACCESSORIES 

An application does not have to do much to support classic desk accessories. It just 
cannot disable interrupts with an SE1 instruction for long periods of time. When 
interrupts are disabled, the GS ignores the Control-OpenApple-Ese keyboard se- 
quence, so the CDA menu will not appear. 

Some programs may need to disable interrupts, but usually only for brief periods 
of time. If you are writing such a program, be sure to execute a CL1 (clear interrupt 
flag! instruction once it is safe to re-enable interrupts. 

Writing a CDA 

A CDA is actually a Pro DOS 16 load file that begins with a special header block 
containing the name of the CDA, the address of the subroutine to be called to start 
it up, and the address of the subroutine to be called when DeskShutDown is called 
Here is the assembly-language format of the header; 

CDA_Header STR 'CDA Name' ;Name (preceded by length) 

DC 14 ■CDA_Startup' ;Startup subroutine 
DC I4'CDA_ShutDwn' ;ShutDown subroutine 

The start-up subroutine contains the main code for the CDA. The Desk Manager 
calls it with a JSL instruction in full native mode when you select the CDA from 
the CDA menu. The subroutine must end with an RTL instruction. 

The Desk Manager calls the shut-down subroutine whenever the DeskShutDown 
function is called. An application normally calls this function just before it quits, 
but it is also called when the operating system switches between ProDOS 16 and 
ProDOS 8- The CDA's shutdown subroutine can terminate any background task the 
accessory may be performing for the current application. In most cases, there are 
no such tasks, so the shutdown subroutine is just a single RTL instruction. 

A CDA can use any of the text screen areas in banks $00, SOI, $E0, $E1 (offsets 
$400-S7FF) without fear of interfering with the current application. This is because 
the Desk Manager saves these areas before displaying the CDA menu and restores 
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them on exit. A CDA may also use zero page (page $00 of bank $00) without 
bothering to preserve its contents as long as it respects those areas used by the 
system monitor subroutines. Any other memory the CDA needs must be allocated 
with the Memory Manager. 

If the CDA is not designed to work with all operating systems, it should check 
location $E100BC to see which one is active and then take the appropriate action. 
The number stored there is $00 for ProDOS 8 or $01 for ProDOS 16. 

Installing a CDA 

The CDA program file must have a file type code of $B9, and you must place it in 
the SYSTEM/DESK. ACCS/ subdirectory of the disk from which you boot. When 
you boot ProDOS 16, the system automatically installs the CDAs it finds in this 
subdirectory. The maximum number of CDAs that may be installed (including the 
Control Panel arid Alternate Display Mode accessories in ROM) is fourteen. 

If the CDA is already in memory, you can install it by passing its handle to 
InstallCDA. You probably will not use InstallCDA often because it is more conven- 
ient to have CDAs installed automatically at boot time. 

NEW DESK ACCESSORIES 

New Desk Accessories are more difficult for an application to support because they 
are more intimately connected to an application. Whereas a CDA takes complete 
control of the cs until you exit it. an NDA shares the screen with the application 
and will not work properly without a helping hand from the application. 

To support NDAs, several tool sets must be loaded and started up before you 
call the DeskStartup function: QuickDraw, Event Manager, Window Manager, 
Menu Manager, Control Manager. Scrap Manager, LineEdit, and Dialog Manager. 
This is necessary because an NDA must be permitted to call functions in these tool 
sets without having to load RAM-based tool sets or having to execute start-up 
hmetions. 

The easiest way to make NDAs available to an application is to use a TaskMaster 
event loop, because TaskMaster makes almost all necessary function calls for you. 
In fact, assuming that the application calls DeskStartup at the beginning and 
DeskShutDown at the end, it need only use FixApplcMenu to add the names of all 
the NDAs to a standard Apple menu: 

PushUlord #1 ; ID number of Apple menu 

_Fi xAppleFlenu 

The NDA items are assigned consecutive menu item ID numbers, beginning with 
1. (Recall from chapter 7 that numbers 1 through 249 are reserved for desk accessory 
Items.) 
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If you are nut using TaskMastrr, NDA support is more complicated and involves 
calling specific Desk Manager functions at appropriate times. The following para- 
graphs describe how TaskMaster controls NDAs and what standard actions have to 
he performed if a GetNextEvent event loop were used, 

TaskMaster knows when the user selects a desk accessory item from the Apple 
menu because MenuSelect returns a menu ID less than 250. When this occurs, 
TaskMaster calls OpenNDA to open the desk accessory, an action that usually causes 
a window for the NDA to appear on the screen. It then controls all window 
management for both desk accessory and application windows, just as it would if 
multiple application windows were on the screen. 

TaskMaster handles mouse-down events in the system window content region by 
calling SystemClick. SystemClick passes the event to the NDA fur processing, 
Standard editing events selected from the Edit menu (Undo, Cut, Copy, Paste, and 
Clear with menu IDs from 250 to 254) arc handled by calling SystemEdit, which 
passes them to the active DA for processing. 

A special close item in a File menu unemi ID 255! is handled by calling 
CloscNDAhyWinPtr. This passes control to the close subroutine defined in the 
NDA. 

TaskMaster also allows NDAs to perform any periodic activity associated with 
them by calling SystemTask once every time it performs its internal event loop. 

Writing an NDA 

Like a CDA. an NDA is a ProDOS 16 load file that begins with a special header 
block. The format of the header block is quite different than that for a CDA, how 
The header-block format looks like this: 

;# of ticks between run actions 
;mask describing events wanted 

{Pointer to open subroutine 

;Pointer to close subroutine 

'Pointer to action subroutine 

■ r Pointer to Init subroutine 



DC C'## r ;Placeholder for length 

DC C'ltem Name' ;Text for the NDA name 

DC C'\H»« ' , 11 '0 ' ;Space of ID + zero byte 

As you can see, the header begins with pointers to lour standard subroutines. They 
will be described below. 

Following the pointers is a word indicating how often the Desk Manager will 
pass a Run code to the N DA _ Act ion subroutine. The basic unit of Period is a timer 
tick (l/60th of a second), so, for example, a Period of 60 would represent one second. 
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Per l od 


EQU 


60 


EventPlask 


EOU 


$FFFF 


NDA_Header 


DC 


l4'NDA,0pen' 




DC 


14'NDAZciose' 




DC 


I4'NDA_Action 




DC 


1 4 • MDA_ Init ' 




DC 


12'Period' 




DC 


J2'EventMa5k ' 



There are two special Period values: tells the Desk Manage* to pass the Run cock- 
as often as possible (in practice, this means oner ever) TaskMaster loop); IFFFF 
tells the Desk Manager not to pass the Run code at all. 

The event mask indicates which events will cause the Desk Manager to pass an 
Event code to the NDA_ Action subroutine, The meaning of the mask is the same 
as that for the event mask described in chapter 5 in connection with the Get- 
NcxtEvent and TaskMaster functions. In most cases you will set it to SFFFF (all 

events). 

The final item in the header is the name of the NDA, in the format expected by 
the Menu Manager. Jl begins with two placeholders for the length ami is followed 
by the text of the name and then a\H** command {this reserves space lor the menu 
A trailing byle marks the end of the item definition. 

The next section takes a close lool at each of the four subroutines an NDA must 
contain. You max want to refer to listing 9-L which shows how to implement a 
clock desk accessory, lor practical implementation instructions. 

$DA_Open. The NDA_Open subroutine must prepare the desk accessory lor use 
but only il "it is not already open In most cases this involves creating a window lor 
the NDA using the NewWindow function, saving the window pointer lor later use, 
and marking the window as a system window using the SetSysWindow function. 

Before the Desk Manager makes a call to NDA.Open with a JSL instruction, it 
reserves space on the stack for a long word result, NDA.Opcn must return the 
NDA's window pointer here before exiting with an RTL instruction. 

On entry to the \DA_Open subroutine (or the other three standard subroutines), 
the 65816 will be in full native mode. At the shirt of the subroutine, you should 
execute PHI3. PHK, and PLU instructions to make the data bank register equal to 
the code bank register. This lets you access memory locations within the 
accessory code space with absolute addressing rather than absolute long addressing, 
sit, be sure to execute a PLB instruction to restore the data bank register to 
its original stale. 

NDA_Ch.se. The NDA.Closc subroutine is responsible for shutting down the 
accessory, usually by closing its window with the Close-Window function. It does 
not return a result. This subroutine is automatically called by TaskMaster il you 
click the close box on the NDA window or if you select the special Close item from 
a menu (it has a menu 11) ol 255). 

NDAJnit. This initialization subroutine is called whenever the application calls 
the DeskStartup or DeskShutDown function. On entry, the accumulator is it a 
call to DeskShutDown was made; it is non-zero for calls to DeskStartup. 

Most initialization subroutines do not have to do anything when DeskStartup is 
called, because the NDA is not even integrated with the application at ibis stage. 
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Table 9-1: Action Codes (for New Desk Accessories 



Action ( 


Task 


I 


Event 

A mouse-down, mouse-up. key-down, autokey-down, update, or 
activate event took place, so process it A pointer to the 
record is in X (low) and V (high). 


2 


Run 

The Period has elapsed, so perform the periodic action. 


3 


Cursor 

The NDA window is active, so change the cursor if necessary. 


4 


| Reserved] 


5 


Undo 

The special Undo item (ID 250) was selected, so process it, 


6 


Cut 

The special Cut item (ID 251) was selected, so process it. 


7 


Copy 

The special Copy item {ID 252) was scln-ir.l. so process it. 


8 


Paste 

The special Paste item (ID 253) was selected, so process it. 


9 


Clear 

The speeial Clear item (ID 25-4] was selected, so process it- 



When DeskShutDown is called, the NDA window should be closed to release the 
memory it occupies or to terminate some activity tied to the application, 

NDA_Action. The most difficult subroutine to program is the action subroutine. 
It is responsible (or handling any of nine tasks that may be passed to it for processing, 
The action code for the task is passed in the accumulator and can be one of the 
values shown in table 9-1, 

For action codes 5 to 9 (the editing commands), a non-zero v.ilue is n turned in 
the accumulator if the action was handled {the usual case) or if it was not. 

The Run task should be processed by performing the periodic action associated 
with the NDA. The clock accessory in listing 9-1. which has a Period of one second, 
processes the Run code by displaying the current time. In other types of accessories, 
you may want to blink a cursor, update .i s\v1*ni status display, or perform other 
similar tasks. 
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The Cursor task is called once every Task Master loop, but only if the NDA 
window is open. It allows the accessory to change the active cursor depending on 
the current position of the mouse. For example, you might want to change the 
cursor to a bulls-eye if" the mouse happens to he inside the content region of the 
desk accessory window. The example accessory shows how to determine if the mouse 
is inside an NDA window, how to change the cursor to a wristwateh if it is, and 
how to restore the original cursor if it is not. 

The Event task handles the six standard GS events mentioned above. The trickiest 
handler is probably the one lor update events. It must call Begin Update (to make 
die visible region the same as the update region temporarily >, redraw the contents 
of the window, and then call End Update (to restore the original visible region and 
empty the update region). The clock NDA redraws the window simply by displaying 
the current time, 

The handler For activate e vents must first distinguish between an activate and a 
deactivate operation. It can do this by examining bit of the modifiers word of the 
event record; if it is 0, the NDA window is being deactivated. In the example, a 
deactivate event is handled by restoring the original cursor. 

Notice the technique med in the example for accessing the modifiers field in the 
event record. On entry to the \DA_Aetion subroutine, a pointer to the event record 
(stored in X and Y) is pushed on the stack, Later, a direct page that is aligned with 
the stack pointer is created so that the fields in the event record, a pointer to which 
is now in direct page, can he accessed with the [dp].Y addressing mode. 

Installing an NDA 

NDAs are ProDOS 16 load files that have a file type code of $B6\ Only those NDA 
files that are located in the SYSTEM/DESKACCS/ subdirectory on the boot disk 
at boot time will be added to the Apple menu when you call the FixAppleVlenu 
(unction. 



REFERENCE SECTION 

Table R9-I: The Major Functions in the Desk Manager Tool Set ($05? 







Function 


Stack 


Description of 


Function Name 




Number 


Parameters 


Parameter 


CloseNDA 




$16 


RefMum (W) 


NDA reference number 


CloseNDAbyWii 


Ptr 


sic; 


TheWindow(L) 


Pointer to CD A 

window 


Desk Startup 




.$02 


|no parameters] 




DeskS hut Down 




$03 


[no para mi i I 
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Function Name 


Function 
Number 


Stack 
Parameters 


Description of 
Parameter 


FixApple.Menu 


S1E 


MenulD (W) 


ID of menu to add DAs 
to 


InstallCDA 


$0F 


IDHandle (L) 


Handle to CDA header 


Open N DA 


$15 


result (W) 


Reference number for 
NDA 






DAlDNumbc. (W) 


Menu item ID number 
for NDA 


SystemClick 


$17 


Event Record (L) 


Ptr to event record 






The Win dim Li 


Ptr to NDA window 

record 






FindWimdRes (W) 


Result of FindWindow 
call 


System Ed it 


$18 


result i\V ; 


Boolean: did NDA 
handle edit? 






EditT>pe (W) 


Code for edit 

command: 

1 = undo. 2 - cut, 
3 = copy, 1 = paste, 
5 = clear 


SystemTask 


819 


[no parameters] 





Table R9-2: Desk Manager Error Codes 



Error 

Code 



$0510 
$0511 



Desc ription of Error Condition 



The specified desk accessory was not found, 

The window is not an NDA [system) 
window. 
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Listing; 9-1; A New Desk Accessory 



llllllltllMUMiOtttllitlllllliillttlllll 

■ T h : ~j p r o q r a m shows he* t e construct B • 

» New Desk Accessory (NDA), The NDA • 

* defined here is a clock window which • 

* contains the current time and date; the B 

• time and date are updated once per * 

• second. " 



LIST 


OFF 


SYMBOL 


OFF 


ABSADDR 


DN 


INSTIME 


ON 


GEN 


ON 



KEEP CLOCK 
MCQPY CLOCK. MAC 



;Code file 
! Macro file 



Period GEGU 60 
EventMask GEQU IFFFF 



;Ask for "run" action every second 
; Handle all events 



HDA Clock START 



DC M'NDA_0pen' 

DC M'NDA.Close' 

DC l4'NDA_Action' 

DC I4'NDA_Imt' 

DC I2'Penod' 

DC 12'EventMask ' 

DC C ' * ' 

DC C 'Clock' 

DC C ' \ H • • • . 1 1 • ' 



Dpen the NDA 
Close the NDA 

Perform HDA action 

Startup/Shutdown the NDA 

Periodicity of "run" action 

Permitted events 

Name in menu item form 

Teat for NDA name 

ID field * terminator 



; Open the NDA if it has not been previously opened. This routine 
; must return a pointer to the NDA window on the stack, just above 
i the 3-byte return address. The Desk Manager reserves this result 
; space just before calling NDA_0pen with a JSL instruction. 



NDA.Dpen 


ANDP 




Result 


EQU 

PHB 
PHK 
PLB 


105 




LDA 


ClockDpen 




BNE 


Ignore 



;ResuH stack offset after JSL, PHB 



; da t a bank = code bank 

;Clock window already open 7 
i 1 f 50 , branch 
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;Space for result 



iCreate and open NDA window 

; Pop pointer [ low) 
;Pop pointer (high) 

;Save pointer to window 



; S a v e result on stack (high) 

; (low) 

PushLong WindowPtr 

_Set SysW indow ■, Mark this as a DA window 

LDA #*FFFF 

STA ClockOpen ;Set "open" flag 

;space for result 

",5ave pointer to regular cursor 



PHA 




PHA 




PushPt r 


WmdowDef 


_NewWi n 


dow 


PLX 




PLA 




5TX 


WindowPtr 


STA 


WindowPtr *2 


STA 


Resul t+2,S 


TXA 




STA 


Result ,S 



Ignore 



PHA 




PHA 




_GetCursorAdr 


PopLong 


QldCuraor 


PLB 




RTL 





; Close the NDA if it is not already closed: 

NDA_Close ANGP 

PHB 
PHK 
PLB *,data bank = code bank 

LDA ClockQpen ;Is the clock window open? 
BEQ Ignore ;No, so branch 

PushLong WindowPtr 

_CloseWindow ;Get rid of the window 

STZ ClockOpen ;Mark clock as closed 

PushLong OidCursor 

_5etCursor ;Restore application cursor 

PLB 
RTL 
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; Perform the NDA action; 

NDA Action ANOP 





PHB 








PHK 








PLB 








PHY 








PHX 








ASL 


fl 






TAX 








JSR 


(ActionTbl ,K) 




PLX 








PLV 








PLB 








RTL 






Ac 1 1 onTbl 


ANDP 








DC 


12 


1 NoAc lion' 




DC 


IE 1 


■NDA.Event' 




DC 


12 ' 


'NDA.Run' 




DC 


12' 


1 NDA_Cursor ' 




DC 


12 


'NDA.Rsvrd' 




DC 


12' 


»NDA_Undo» 




DC 


:z 


•NDA_Cut ' 




DC 


IS 1 


'NDA_Copy' 




DC 


12 


'NDA_Pa5te' 




DC 


12 


'NDA_Clear' 


NoAct ion 


ANOP 
RTS 






NDA_Rsrvd 


ANOP 
RTS 






NDA_Undo 


ANOP 






NDA_Cut 


ANOP 






NDA_Copy 


ANOP 






NDA_Paste 


ANOP 






NDA_Clear 


ANOP 







iSave data bank 

; flake data bank ■ program bank 

;5ave incoming parameters 
;(event record or menu info) 

;x2 to step into table 



; F i x up the stack 



i Dn exit A=Q if edit command wasn't handled; non-zero if it was. 

; You will usually want to say it was handled, because the application 

; will not be active and so shouldn't be dealing with edit commands. 

LDA #JFFFF ;Say we handled it. 

RTS 
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Display a wristwatch cursor if the cursor is over top of 

the content region of the window. This routine is only called 

when the DA window is the front window. 

NDA.Cursor ANDP 

PHA 
PHA 

_GetPort jSave current GrafPort 

PushLong WindowPtr 

^SetPort "Make clock window active GrafPort 

PushPtr PortRect 

_GetPortRect ;Get the port rectangle (local coords) 

PushPtr MousePosn ;Return position in GrafPort coords 

_GetMouae ;Get cursor position 

PHA ;space for result 

PushPtr MousePosn ;pointer to mouse coordinate 

PushPtr PortRect *, pointer to content region rectangle 
_Pt InRect 

PLA ;l5 point in content region' 

BEQ NDA_Curs1 ;No, so branch 

; Switch to watch cursor, but only if it's not already actives 



■»Get current cursor pointer 



; 1 5 it the watch' 
;De finitely not 
(Is it the watch'' 
J V e 1 , so do nothing 

NDA_CursQ PuahPtr WatchCurs 
BRA NDA_Curs2 

; Switch to application cursor, but only if it's not already active: 

NDA_Cur 5 1 PHA 
PHA 

_Get Cur sor Adr ;Get current cursor pointer 

PLA 

PLX 



PHA 




PHA 




_GetCur 


5 or Ad r 


PLA 




PLX 




CP1P 


#WatchCura 


BNE 


NDA_CursO 


CPX 


#*WatchCurs 


BEQ 


NDA_Curs3 
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CMP 


'WatchCurs 


BNE 


NDA_Cui-53 


CPX 


#*WatchCur5 


BHE 


NDA_Curs3 



-, 1 5 it the watch? 

;No, bo don't do anything 

;Ia it the watch? 

;No, so don't do anything 

PushLong OldCursor ;5witch to application cursor 

NDA_Curs2 _SetCursor 

NDA_Curs3 _SetPort ;Restore GrafPort 

RTS 

; This subroutine is called once every "Period" ticks; 

HDA.Run ANOP 

PHA ;5pace for result 

PHA 

_GetPort ; Save current port 

PushLong WindowPtr 

_SetPort *, Switch to clock window for drawing 

JSR ShowTime ^Display the new time 

_SetPort -.(Pointer still on stack) 

RTS 

j X and ¥ (pushed on stack) contain pointer to event record 

NDA.Event ANOP 

;1 (base) ♦ 2 (JSR) * 2 (PHD) 



; Align d . p . with stack 

•Get "what" code 
'♦Anything we support** 

;No, 50 branch 

■, x 2 to step into table 



TheEvent 


EQU 

PHD 
TSC 
TCD 


SOS 




LDA 


CTheEvent 3 




CMP 


#9 




BCS 


TE1 




ASL 


fl 




TAX 






JSR 


(EventTbl ,X 


TE1 


PLD 






RTS 





-.Restore direct page 
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EventTbl 


ANOP 




DC 




DC 




DC 




DC 




DC 




DC 




DC 




DC 




DC 


DoMouseUp 


ANOP 


Doflou seDwn 


ANOP 


DoKeyDwn 


ANQP 


DoAutoKey 


ANQP 


NoEven t 


RTS 


DoUpdate 


ANOP 



12'NoEvent ' 

1 2 f DoMouseDwn ' 

12'DoMouseUp' 

I2 r DoKeyDwn' 

I2'NoEvent « 

I2'DoAutoKey r 

I2'DoUpdate» 

I2'NoEvent' 

I2 r DoAct ivate' 



Not supported 

Mouse-down 

Mouse-up 

Key down 
Not supported 

Auto key 

Update 
Not supported 

Activate 



PuahLong WindowPtr 
_Begi nUpda te 



JSR 



ShawTime 



PushLong WindovuPtr 
_EndUpdate 

RTS 

; If NDA window Is deactivated, n 

DoActivate ANOP 





LDY 


#14 




LDA 


[TheEvent] ,Y 




AND 


#101 




SEQ 


NDA.Off 




RTS 




NDA_0ff 


PushL 


ong OldCursor 




_SetC 


u r a o r 




RTS 





^Visible region ■ update region 
■,Diaptay the current time 

'.Restore entire visible region 
turn to original cursor. 



*,Access modifiers field 

; Isolate activate/deactivate flag 
; If , deact i vate 



; Switch to previous cursor 



ShowTif 



ANOP 

PushPtr TheTime 
ReadAsci i Time 



SEP 
LONGA 



OFF 



'jRead the clock 

; 8-bit A register for byte accesses 
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LDY 


*-1 9 


LDA 


TheTime, Y 


AND 


#J7F 


STA 


TheTime , Y 


DEr 




BPL 


ST1 


REP 


*S20 


LGNGA 


ON 


PushWor 


d #20 


PushWor 


d #9 


MoveTo 





;Convert to standard ASCI 1 



;Back to 16-bit A register 



;hor i rental 
; vertical 



PushPtr TheTime 

_DrawCStnng ;Draw the time strinc 

RTS 



I Startup or shutdown the NDA . On entry, A = for DeskShu tDown i, 
; A is non-zero for DeskStartup. 

NDAJnit ANDP 

PHB 

PHK 
PLB 

CNP #0 ^Starting up? 

BNE NDA_Init1 ;Yea, so do nothing 

LDA Clock Open ; Clock window open? 
BEG NDA.Imtt ; No, so branch 

PushLong WimdowPtr 

_C loseUli ndow -Close the window (releases memory) 

STZ ClockOpen -,Set "closed" flag 

NDA_lnit1 PLB 
RTL 

! The data area begins here: 

NDA.Title STR 'Calendar/Clock 1 ;Window title 

WindowDef ANQP 

DC 12'EndWind-UindowDef 

DC I2'%1 100000010100000' ;Window with close box, title 

DC H'NDA_Title* '.Pointer to window name 
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DC 


1 4 ' ' 




DC 


I2 1 t ,0 r 0> 




DC 


14' 0' 




DC 


1 4 ' * 




DC 


I 4 ' ' 




DC 


14'0< 




DC 


I4'0« 




DC 


I4'0« 




DC 


I4'Q« 




DC 


I2'0' 




DC 


14 » ■ 




DC 


I4'0» 




DC 


I4'0» 




DC 


I '60,65,71 ,245 




DC 


14 ' -1 » 




DC 


14 ' ' 


EndWind 


ANOP 




Wi ndowP t r 


DS 


4 


C loc kOpen 


DS 


2 


PortRect 


DS 


B 


MousePosn 


DS 


■1 


TheTime 


DS 


20 




DC 


C ' 




DC 


M « ' 



; Origin at (0,0) 



OldCursor DS 



(Handle our own updates) 

Dimensions of window 

Put clock window in front 



;Pointer to window record 
;Used as a flag 

;Content region rectangle 

; Current mouse position (local) 

*, ReadAsci iTime returns 20 bytes 

;Add padding 

;( terminator for DrawCStr mg) 

;Pointer to application's cursor record 



; This is the cursor record for a "wr 1 stwatch" cursor: 



NatchCurs DC 
DC 

DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 

DC 
DC 
DC 



12M2' 


I2»3' 


H 


000000000000' 


H 


000FFO00OOOO' 


H 


0QQFFQQQ0QQQ' 


hi 


00F0OFOO0000' 


H 


0F00F0FO0000' 


H 


QF0QF0F000QQ' 


H 


0F0FF0FFOO00 1 


H 


QFQ00QFOOO0D' 


H 


O0FQQFOQOO0D' 


H 


QOQFFQQOQO0G' 


H 


OOOFF0000000 1 


H 


000000000000' 



;Rows in cursor image 
;Cursor width (in words) 

; The cursor image 



H'OOOFFOOOOOOO' 
H'OOFFFFOOOOOO' 
H'OOFFFFOOOOOO' 



;The cursor mask 
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DC 


H' 


OFFFFFFQOOOO' 


DC 


H' 


FFFFFFFFOOOO' 


DC 


H" 


FFFFFFFFOOOO 1 


DC 


H ' 


FFFFFFFFFOQQ' 


DC 


H' 


FFFFFFFFOOOO 1 


DC 


H i 


QFFFFFFOQQQQ' 


DC 


H i 


OOFFFFOQQOQO' 


DC 


H< 


OOFFFFOOOOOO' 


DC 


H 1 


'OOOFFQQOQQQQ' 


DC 


I2»6,8' 


END 







■, Hot spot (y,x) 
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CHAPTER 10 



The ProDOS 16 

Operating 

System 



The software interface between an application program and a mass-storage device 
such as a disk drive is called a disk operating system. Its main responsibilities are 
to organize data and program files on the disk medium and to provide a simple 
mechanism applications can use to transfer data to and Ironi these files. Other 
common chores a disk Operating system performs are file creation, deletion, and 
renaming, and volume management. 

For the past leu years, the standard operating system for the Apple II family has 
been ProDOS, the Professional Disk Operating System. The original release of 
ProDOS, since renamed ProDOS 8, was designed specifically for the lie, He, and 
II Plus, and works in the 65CU2's (or 6502s} 64 K memory space only. 

ProDOS 8 also works with a cs that is running He-style applications, of course, 
but it will not work with OS-specific applications, because they are not confined to 
the first 64k of memory- To solve this problem, Apple Computer, Inc. created 
ProDOS 16. an operating system that is similar in structure to ProDOS H but that 
takes advantage of the entire c.s memory space, 

ProDOS 16 runs in 65816 native mode, which means it works on the Apple lies 
only. If you try to boot it on another type of Apple II you will see an appropriate 
error message. Programs that work with ProDOS 8 will not work with ProDOS 16, 
because ProDOS 16 uses a new command calling sequence. Fortunately, program- 
mers should find it relatively easy to adapt programs to ProDOS 16, because most 
ProDOS S commands have ProDOS 16 equivalents with the same symbolic names 
and similar types of command parameters 

Both versions of ProDOS format disks and store files in exactly the same way. 
Thus, data files can be accessed directly by either operating system. ProDOS 16 is 
even capable of" switching to ProDOS H if the proper system files are included on 
the start-up disk. 



This chapter looks at the main features of ProDOS 16 and gives several examples 
of how to use ProDOS 16 commands from within a program, It also reviews some 
of the jargon associated with ProDOS in general and ProDOS 16 in particular. 
ProDOS 8 has been covered in great detail in Apple ProDOS: Advanced Features 
for Programmers (Little, 1985), That subject matter will not be repeated here, 

BLOCK-STRUCTURED DEVICES 

ProDOS 16 works with bkyck-structurnl storage devices only. A block is a group of 
512liytes of data and represents the smallest unit of information the device controller 
can read or write. Contrast this with character devices, such as printers or modems 
which deal with only one character at a time. 

The most common block-structured devices used with ProDOS In" on the GS are 
the following disk drives: 

• 3 Vfe-inch disk drives (Apple 3.5 Drive, LJniDisk 3.5) 

■ 5 Va -inch disk drives (Apple 5.25 Drive UniDisk 5.25. DuoDisk, Disk II) 

• Hard disks (Hard Disk 20SC, ProFile) 

Appendix 7 describes how to connect 3 ' 2-inch and 5 14-inch drives to the cs. 

In addition, it is possible to partition arid configure an area of memory so that 
ProDOS 16 thinks it is a block-structured device called a RAM disk. The advantage 
of using a RAM disk instead of a mechanical disk drive is that input/output operations 
are much quicker. You must remember lo save files on the RAM disk to a real disk 
before you turn off the GS, however. 

The easiest way to create a HAM disk is to use the Control Panel desk accessory. 
With it vou can allocate all or a portion of the memory on a CS memory expansion 
card for RAM disk use [fyou formal this RAM disk and put the necessary operating 
system Hies on it, yon can even boot from it when you press Control-OpenApple- 
Reset. To select it as the boot device, use the Control Panel Slots command to 
change the Boot option - 

DIRECTORIES AND FILES 

A volume is the general name lor the storage medium used by a block-structured 
device. Each volume formatted by ProDOS 16 contains one or more directories in 
which files may be stored. The main directory, called die vohme directory or the 
root directory, is created when you format the disk; it may contain up to 51 entries, 
representing ordinary data files or subdirectory files. A subdirectory may contain as 
many entries as space permits, including other subdirectories. See figure 10-1 for 
a diagram showing how multiple directories on a volume are interrelated. 

The ability to create a hierarchy of directories makes it easy to manage large 
numbers of files on a single disk, This is because groups of related files can be 
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Figure 10-1. The ProDOS Hierarchical Directory Structure 



Volume Directory 



/WORK/ 



PRODOS SYS 

BASIC.SY5TEM SYS 

STARTUP BAS 

LETTERS DIR 

PROGRAMS DIR 



/VQRK/PROGRAMS/ 



PROGRAMS/ 



ANIMALS BAS 
PTP.CODE SYS 
PTP.16 S16 



/VORK /LETTERS/ 



LETTERS/ 



TG.EDITOR 
GS.BOOK 



TXT 
DIR 



/VORK /LETTERS /GS.BOOK/ 



GS.BOOK/ 



CHAPTER. 1 TXT 
CHAPTER.2 TXT 



isolated in their own separate directories where they will not be mixed with the 
many other files on the disk. 

Every file on a disk is associated with a filename up to fifteen characters long. 
The first character must he a letter of the alphabet from A to Z, but subsequent 
characters can be letters, digits (0 to 9), or periods. 

Because of the way directories can be nested when using ProDOS 16, it is not 
enough to identify a file by its name only. You must also identify the directory in 
which the file is stored. The identifying string required by ProDOS 16 is called a 
pathname. It is a concatenation of the names of each of the directories ProDOS 16 
must pass through to reach the file's subdirectory, followed by the name of the file 
itself. The pathname begins with a slash (/) and each directory name in the pathname 
is separated from the next with a slash. 

Suppose the name of the volume directory of your disk is WORK and within this 
directory you have defined a subdirectory called LETTERS that contains a file called 
TO.ED1TQK. The pathname to use to identify this file is: 

/WORK /LETTERS /TO, ED I TOR 
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You can avoid specifying a complete pathname every time you want to deal with a 
file by setting a default prefix. A default prefix identifies the path to a particular 
director}', and ProDOS 16 automatically puts that path In front of any filename you 
specify. It will also put it in front of .1 partial pathname. A partial pathname is a 
name describing a series of directories that does not begin with a slash. Essentially, 
a partial pathname is the pathname of a file relative to the directory described by 
the default prefix. 

For example, it you set the default prefix to WORK/LETTERS in the above 
example, you could identify TO. EDITOR by its filename only, if the default prefix 
was /WORK;, you would specify the partial pathname LETTEKS/TO. EDITOR 

'Die default prefix can also be represented by the name 0/. Thus, 0/TO. EDITOR 
is equivalent to /WORK/LETTERS, TO- EDITOR if the 0/ prefix has been sel to 
/WORK/LETTERS. When an application first starts up, the default prefix identifies 
the name of tin- boot volume 

As indicated in table 10-1. ProDOS 16 has a similar shorthand notation for the 
prefixes describing eight other directories. Only 07 and 3/ to 7/ should be changed 
by an application, although it is possible to change 1/ and 2/ if you really need to. 
Change prefixes with the SET_PREFL\ command, 

THE STRUCTURE OF A PRODOS 16 BOOT DISK 

Certain files must be present on a ProDOS 16 system disk before you can boot it 
or use it to run both ProDOS 8 and ProDOS 16 applications. The structure of the 

simplest such system disk is as follows 

PRODOS Operating system loader 

SYSTEM/ Subdirectun : operating sysLi 111 lih- 

PB The ProDOS 8 operating system 

P1 6 The ProDOS 16 operating system 

START The start-up program 

TOOLS/ Subdirectory: RAM -based tool sets 

FONTS/ Subdirectory: font files 

DESK.ACCS/ Subdirectory: desk accessories 

LIBS/ Subdirectory: system library files 

DRIVERS/ Subdirectory; device drivers 

SYSTEM , SETUP/ Subdirectory: initialization programs 
TOOL . SETUP Patches to ROM-based tool sets 

A ProDOS 16 system disk goes through a rather convoluted start-up procedure 
when you boot it. It begins by loading the ProDOS program into memory and 
executing it. Once ProDOS gets control it loads the ProDOS 16 operating system 
from the SYSTEM/PIG file and then executes the TOOL. SETUP program in the 
SYSTEM7SYSTEM.SETUP/ directory. TOOL.SETL'P patches and enhances HUM. 
based tool sets, 
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Table 10-1: .Standard Prefix Numbers 



Prefix 




Number 


Description 


*j 


The boot prefix 




This is the volume name from which Pro DOS 16 was 




booted. This prefix cannot be changed. 


11/ 


The default prefix 




ProDOS automatically attaches it to any filename or partial 




pathname (as opposed to full pathname! you specify. 


1/ 


The application prefix 




The pathname of the directory containing the current 




application program. 


2/ 


The system library prefix 




The pathname of the director) containing library modules 




used by the current application. For a standard ProDOS 16 




boot disk, this is /MYDISK/SYSTEM/L1BS/. 


3/ 


I'ser-dcfinable 


y 


User-definable 


5) 


User-definable 


67 


User-definable 


7/ 


User-definable 



ProDOS then continues by loading and executing every other file in the SYSTEM/ 
SYSTEM* SETUP/ directory. Typical files include permanent initialization (start-up) 
files with file type codes of $B6 and temporary initialization files with file type codes 
of $B7, The difference between these two types of files is that temporary initialization 
files remove themselves from memory when they finish executing; permanent ini- 
tialization files do not. 

ProDOS then moves to the SYSTEM/DESK.AGCS/ directory and loads into 
memory any Classic Desk Accessory files (file type SB9) and New Desk Accessory 
files (file type SBH). This causes the names of the Classic Desk Accessories to be 
placed in the menu that appears when you press Control-OpenApple-Esc, 

Next, ProDOS searches the SYSTEM directory for a file called START that has 
a file type of $B3 (S16). If it finds this file, it loads and executes it and the boot 
process ends. The START program is typically a program selector that lets you 
choose a particular application to run. 
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If PRODOS does not find START, it scans the volume directory until it finds a 
Pro DOS 8 system program (file type SFF) whose name ends with ".SYSTEM" or a 
ProDOS 16 system program (file type |B3) whose name ends with *.SYS16. * It then 
ends ihe boot procedure by running the program. It will not run a ProDOS 8 
program unless SYSTEM/P8 is on the disk, however. IF no such system program is 
found, PRODOS brings up a window asking the user to enter the pathname of the 
application to run. 

USING PRODOS 16 COMMANDS 

The general procedure lor calling a ProDOS 16 command is different from the one 
used to call a tool set function. It goes something like this: 

JSL 1E100A8 ;Call ProDOS 16 entry point 

DC I 2 " CammandNum ' ; Command number [word] 

DC 1 4 ' ParrnTab le 1 ;Addresa of parameter table [long! 

BCS Error ifControl resumes here after call) 

You can call a ProDOS 16 command while the 65816 is in native mode. 

Immediately following the JSL instruction is a word containing the identification 
number of the ProDOS 16 command you wish to use. Table 10-2 contains a list of 
all 32 ProDOS 16 commands and command numbers. 

Following the command number is a pointer to a parameter table containing 
parameters required by the command and results returned by the command. The 
parameters can be one- or two-word numeric values or two-word pointers. The 
exact structure of the parameter table varies from command to command. 

When a ProDOS 16 command finishes, it adds 6 to the return address pushed 
on the stack by the JSL instruction, then ends with an RTL instruction. This causes 
control to pass to the code beginning just after the pointer to the parameter table. 
On return, all registers remain unchanged except the accumulator (which contains 
an error code), the program counter, and the status register (the m, x, I, and e Hags 
are unchanged; N, V, and Z are undefined; the D flag is cleared; the carry Hag 
reflects the error status). 

At this stage, you can check the state of the carry flag to determine whether an 
error occurred: if the carry Hag is clear, there was no error; if it is not clear, an error 
did occur. An error code indicating the nature of the error comes back in the 
accumulator; the accumulator will contain if no error occurred, See table R10-2 
in the reference section at the end of this chapter for a list of ProDOS 16 error 
codes. 

APW comes with a set of macros which will help to simplify the use of a ProDOS 
16 command. They are stored in a file called M 16. PRO DOS. To call a ProDOS 
command with a macro, use instructions of the lorm: 

_CMDNAME ParmTbl 
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Table 10-2: The ProDOS 16 Commands 



Command Number 


Command Name 


Description of Command 


$01 


CREATE 


Creates a new file 


$02 


DESTROY 


Deletes a file 


$04 


CHANGE.PATH 


Renames a file or moves it to 
another directory 


$05 


SET_FILE_l\FO 


Changes the attributes of a file 


$06 


GET.FILEJNFO 


Returns the attributes of a file 


$08 


VOLUME 


Returns the name and attributes of 
the volume in a device 


$09 


SET.PREFIX 


Assigns a pathname prefix to one of 
the eight standard prefix numbers 


SOA 


GET. PREFIX 


Returns the pathname prefix for one 
of the eight standard prefix numbers 


SOB 


CLEAR. BACKUP.BIT 


Clears the "backup -needed" bit in a 
file's access code byte 


SKI 


OPEN 


Prepares a file for subsequent read, 
write, and positioning commands 


Sli 


NEWLINE 


Sets the end-of-line character for 
read operations 


S12 


READ 


Reads data from an open file 


$13 


WRITE 


Writes data to an open file 


$14 


CLOSE 


Prevents access to a file until it is 
reopened 


$15 


FLUSH 


Writes the contents of the files I/O 
buffer to disk 


$16 


SET.MARK 


Sets the active position in an open 
file 


$17 


GET_MARK 


Returns the active position in an 
open file 


$18 


SET.EOF 


Sets the size of the file 


$19 


CET.EOF 


Returns the size of the file 
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Table 10-2: Continued 



Command Number 


Command Name 


Description of Command 


S1A 


SET_LEVEL 


Sets the system file level 


$1B 


GET_LEVEL 


Returns the system file level 


$20 


GET_DEV_NUM 


Returns the number of a named 
device 


$21 


GET_LAST_DEV 


Returns the number of the last 
device accessed 


$22 


BEAD.BLOCK 


Reads a block of data from a device 


$23 


W RITE _B LOCK 


Writes a block of data to a device 


$24 


FORMAT 


Formats the medium in a device 


$27 


GET.NAME 


Returns the filename of the current 
application 


$28 


GET_BOOT_VOL 


Returns the name of the Pro DOS 
boot volume 


$29 


QUIT 


Exits the current application 


$2A 


GET.VERSION 


Returns the ProDOS version number 


$31 


ALLOCJNTERRUFI* 


Installs an interrupt handler 


S32 


DEALLOC_lNTERRUPT 


Removes an interrupt handler 



where CMDNAME represents the name of the command and ParmTbl represents 
the address of the parameter table associated with the command. At assembly time, 
this macro is expanded into the standard ProDOS 16 calling sequence. 

The main advantage of using the macros is you do not have to memorize command 
numbers, only command names. It also makes assembly language programs that use 
ProDOS 16 a lot easier to read. 

In the sections which follow, parameter tables for ProDOS 16 commands are 
presented. These tables describe the order of the parameters, the size of the 
parameters, and whether the parameter is an Input (1) or a Result (R), An Input is 
a parameter that must be provided before using the command. A Result (R) is a 
parameter returned by the command. 

Note that even though a pointer to a string may be marked as a result, ProDOS 
16 does not actually return the pointer Instead, it returns the bytes in the string 
in the space pointed lo by the pointer. It is the responsibility of the application to 
allocate a space of the proper size and to provide a pointer to it. 
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FILE MANAGEMENT COMMANDS 

The ProDOS file-management commands perform a variety of important operations 
on closed files: 

• Creating, destroying, and renaming files 

• Reading and changing file attributes 

• Reading and changing pathname prefixes 

The first two groups of commands affect only the directory entry for a file, not the 
data inside the file. 

Creating New Files 

The file management command you will probably use most often is CREATE, With 
it you can create a directory entry for a data file, you can subsequently open this 
file and write data to it. You can also use CREATE to create subdirectory files. 

The parameter list for CREATE is quite lengthy, because it must contain all the 
attributes for the file. Here is how it is structured: 



CREATE ($01) 



Offset 


Symbolic 

Name 


Input 

or 
Result 


Description 


+ to +3 


pathname 




Pointer to the pathname string 


+4 to +5 


access 




Access code 


+6 to +7 


filc_type 




File type code 


+8 to +11 


aux.lype 




Auxiliary type code 


+ 12 to + 13 


storage_type 




Storage type code 


+ 14 to +15 


create, date 




Creation date 


+ 16 to +17 


create _ti me 




Creation time 



Every item in the CREATE parameter list is an input parameter, so each must be 
set up properly before calling CREATE, Multibyte items are stored with the low- 
order bytes first, as usual. 
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There are many unfamiliar items in this parameter list that require further 
explanation; the same items appear in the parameter tables of many other ProDOS 
16 commands. Each item is examined in detail below. 

Pathname, This item is the address of a pathname string identifying the file to be 
created, The string begins with a length byte and is followed by ASCII-encoded 

characters. 

Access. The access item indicates whether the file may be read from, written to, 
renamed, or destroyed; it also indicates whether the file has been modified since 
the last back-up operation. Only the low-order byte ol access is defined (the high- 
order byte is Q)j the meaning of each bit is as follows; 



6 



D 



RN 



B 



[reserved] 



o 



W 



The abbreviations in this chart have the following. meanings: 

* D = delete-enabled 

* RN = re name -enabled 

* B = back-up required 

* \V = write-enabled 

* R = read -enabled 

The access attribute for a particular bit is enabled if the corresponding hit is 1; if 
the bit is 0, the attribute is disabled 

When creating standard files, with lull access permitted, set access to $E3. If 
some of the access attributes are disabled, the file is said to be locked. 

ProDOS 16 automatically sets the back-up bit to 1 whenever you write to the 
file to inform a back-up utility program that the file has changed since the last back- 
up. It is the responsibility of the back-up to clear this bit to with the CLEAR. 
BACKUP_Bn command after making the back-up. 

Filejype, The low -order byte of the file type code indicates the general nature 
of the data the file contains (The high-order byte is always 0.) A list of the eommonlv- 

used codes is provided in table 10-3. 
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Table 10-3: 


ProDOS 16 File Type Codes 


File Type 


Standard 




Code 


Mnemonic 


Description of File 


$00 




Uneatcgorized file 


$01 


BAD 


Bad block file 


S02 


PCD 


Pascal code (SOS) 


m 


FIX 


Pascal text (SOs 


$04 


TXT 


ASCII textfile 


$1X1 


PDA 


Pascal data (SOS) 


S06 


BIN 


General binary file 


$07 


FNT 


Foul file (SOS) 


106 


FOT 


Graphics screen file 


S09 


BA3 


Business BASIC program (SOS) 


$0A 


DA3 


Business BASIC data (SOS) 


SOB 


WPF 


Word proeessor file (SOS) 


*0C 


SOS 


SOS system file 


$0D-$0£ 




[Reserved for SOS] 


SOF 


DIR 


Subdirectory file 


SIO 


RPD 


Record Processing System data (SOS) 


$11 


RPr 


Record Processing System index (SOS) 


$12 




AppleFile discard file (SOS) 


$13 




AppleFile model file (SOS) 


$14 




AppleFile report format file (SOS) 


$15 




Screen library file (SOS) 


$16-$18 




[Reserved for SOS J 


S19 


ADB 


AppleWorks database file 


J1A 


AWP 


AppleWorks word processing file 


SIB 


ASP 


AppleWorks spreadsheet file 


S1C-$AF 




i ved] 


SBO 


SRC 


APW source code 
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Table 10-3; 


Continued 




File Type 
Code 


Standard 
Mnemonic 


Description of File 


SB1 


OBJ 


APVV object code 


*B2 


I, J 11 


APVV library 


SB3 


S16 


ProDOS 16 system program 


$B4 


RTL 


APW run-time library 


$B5 


EXE 


APVV executable shell application 


$B6 


STR 


ProDOS 16 permanent intt (start-up) file 


$B7 


TSF 


ProDOS 16 temporary init file 


$B8 


ND,\ 


New Desk Accessory 


$B9 


CDA 


Classic Desk Accessory 


$BA 


TOL 


Tool set 


$BB 


DRV 


ProDOS 16 device driver 


$BC-$BE 




[Reserved for ProDOS 16 load files] 


$BF 


DOC 


ProDOS 16 document file 


$C0 


PNT 


Compressed super high-res picture file 


$C1 


PIC 


Super high-res picture file 


$C2-$C7 




[ Reserved] 


$C8 


FON 


ProDOS 16 font file 


SC9-SEE 




[Reserved] 


SEF 


PAS 


Pascal area on a partitioned disk 


$F0 


CMD 


Pro DOS 8 added command file 


$F1-$F8 




ProDOS S user-defined files 


$F9 


P16 


ProDOS 16 file 


$FA 


INT 


Integer BASIC program 


$FB 


IVR 


Integer BASIC variables 


$FC 


BAS 


Applesoft BASIC program 


$FD 


VAR 


Applesoft BASIC variables 


$FE 


REL 


E DAS. VI relocatable code file 


$FF 


SYS 


ProDOS 8 system program 


NOTE: SOS stands far the Apple 


III Sophisticated Operating 
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Auxjype. The meaning of ihe auxiliary type code for a file depends on the file 
type code. A texthle, for example, uses the auxiliary type code to indicate the 
random-access record length (or for a sequential texthle not divided into separate 
records). APW uses the auxjype code in SRC ($B0) files to hold a language ID 
number. Note that only the low-order word of aux.tvpe is presently used by ProDOS 
L6. 

Storage Jype. The low-order byte of the storage type code indicates the structure 
of the file on the disk. The possible values are: 



900 

SOI 
$02 



SOD 
$0E 
$0F 



Inactive entry 

Seedling file (EOF <= 512 bytes) 

Sapling file (512 < EOF <= 128K bytes) 

Tree file (128K < EOF < 16M bytes) 

Pascal region on a partitioned disk 

Subdirectory file 

A subdirectory header 

A volume directory header 



The differences among a seedling, a sapling, and a tree file are really not important 
to the designer of an application program. Suffice to say that all standard data files 
should have a storage type of $01 (seedling); as the file grows in size, ProDOS 16 
automatically change* its structure into that of a sapling file and then into a tree 
file. For a description of these three basic file structures, refer to Apple PruDOS: 
Advanced Features for Programmers (Little, 1985). If you are creating a subdirectory 
file, set storage_typc to SOD. 

Create_dttte. The creation date is a two-byte value containing the year, month, 
and day on which the file was created. The encoded formats of these three quantities 
are as follows; 



15 14 1 3 12 1110 9 

■ — t— • 1 1 1 1— 



year 



8 7 



6 5 



month 



4 3 2 

— i »- 



day 



i o 

i — i — 



If you specify a creation date of 0, ProDOS 16 automatically uses the current date. 

Create _time. The creation time is a two-byte value containing the hour and minute 
on which the hie was created. These two quantities are encoded as follows: 
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15 14 13 T2 1t 10 9 



7 6 5 4 3 2 1 









1— — 1 1 1 

hour 








— 1 1 1 1 1 

minute 



If you specify a creation time of0„ ProDOS 16 automatically uses the current time. 

Deleting Files 

To remove a file from its directory permanently, you must delete the file with the 
DESTROY command. Destroying a file also frees up the disk blocks used by the 
file, making them available for allocation to other files. 

The only item in the DESTROY parameter list is a pathname pointer 



DESTROY ($02) 



Offset 



+0 to +3 



Symbolic 
Name 



pathname 



Input 

or 

Result 



I 



Description 



Pointer to the pathname string 



Note that you cannot destroy a file if the delete-enabled bit in its access code is 0. 
You can use SET_FILE_INFO (see below) to set this bit prior to destroying a file. 

Renaming Files 

The most common use for tin CHANGE. PATH command is to rename a file, bill 
it is also useful for moving a file from one subdirectory to another on the same disk. 
Its parameter tabic- looks like this: 



CHAN(.E_PATH ($04) 



Offset 



Symbolic 
Name 



Input 

or 

Remit 



Description 



+Q to +3 par 1 1 name 1 

^4 to +7 new _path name I 



Pointer to the pathname string 
Pointer to the new pathname string 
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When the two pathnames specified are identical except for the filename portion, 
CHANCE_PAT11 simply renames the file If the pathnames describe files in differ- 
ent directories, the entry For the file in the first directory specified is moved to the 
second. 

Note that you cannot rename a file if the rename- enabled bit in its access cade 
is 0. You can use SET_FlLE_lNFO (see below) to set this hit prior to renaming a 
file. 

Changing File Attributes 

As was discussed in the examination of the CREATE command, each file is associated 
with a set of attributes thai describes such things as the date and time on which the 
file was created, the file type, the auxiliary type code, and so on. You can determine 
whal these parameters arc for any existing file using the CET_FILE_1NFG com- 
mand. Here is what its parameter table looks like; 



GET_FILE_ 


INFO (S06) 










Input 






Symbolic 


or 




Offset 


Xante 


Result 


Description 


+ to +3 


pathname 


1 


Pointer to the pathname string 


+4 to +5 


access 


P 


Access code 


+6 to + 7 


file_type 


R 


File type code 


+8 to + 1 1 


aux_lypc 


11 


Auxiliary type code 1 


+ 12 to +12 


storage, type 


R 


Storage type code 


+ 14 to +15 


create_date 


R 


Creation date 


+ 16 to +17 


create_tinte 


R 


Creation time 


+ 18 to +19 


mod_date 


R 


Modification date 


+20 to +21 


mod_time 


K 


Modification time 


+22 to +25 


blocks.tised 


R 


Blocks used by the file 


For a vulurne 


iirector) file, lliis field becomes total.blocks 


(the number of blocks on the volume). 



The only input parameter is the pathname describing the file you want to examine. 
All other parameters are returned by CET_FlLE_INFO. 



File-management Commands 34.3 



The last three types of parameters in the chart above have not been discussed 
yet: 



\loiI_tfati>. The date on which the file was last modified. The format of this 
word is the sa47ie as that for create_date. 

Modjime. The time at which the file was last modified. The format of this word 
is (lie same as that for ereate_tjme. 

Blocks _u,\c(l. The total number of blocks used by the file. It includes any non- 
data blocks used as overhead by the operating system. 

The results returned by CET_FlLE_INFO are slightly different if the pathname 
points to the name of the volume directory of the disk. In this case, the aux_type 
field contains the size of the disk in blocks (called total blocks) and the bloeks.used 
field contains the total number of blocks used by all files on the disk. 

You can use a related command, SET. FILE. INFO, to change the attributes of 
any file; its parameter table looks just like the one used for GET_FlLE_IN'FO, 
except that it does not include the blocks. used field at die end. An easy way to 
change one particular file attribute without affecting the rest is to call GET_FILE_ 
I MO, store the new parameter in the CET_FlLE_INFO parameter table, and 
then call SET_FJLE_I\FO using the same parameter table. Note, however, that 
you cannot change the storage. type attribute with SET_FILE_IXFO. 

Note that SET_FILEJNFO cannot be used to clear the back-up-needed bit of 
the access code word. This bit is primarily for the benefit of disk- back-up utilities. 
By examining the bit, such utilities can determine if a file has changed since the 
last back-up. After the back-up operation, the back-up utility should clear the back- 
up bit to 0. To do this, it must use the CLEAR. BACKUP. BIT command. Here is 
the structure of the parameter table for CLEAR.BACKUP.BIT: 



CLEAR. BACKUP.BIT (SOB) 



Input 
Symbolic or 

Offset Name Result Description 



+G to +3 pathname I Pointer to the pathname string 

Notice that all you have to specify is a pointer to the pathname string. 
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Determining Volume Characteristics 

The VOLUME can be used to determine some of ihe characteristics of a disk 

volume: 



VOLUME 


iSO.Si 






Offset 


Symbolic 
Name 


Input 

or 

Result 


Description 


+0 to +3 


dev_name 


1 


Pointer to the device name string 


+4 to +7 


vol_name 


R 


Pointer to the volume name string 


+8 to +11 


total _blocks 


R 


Size of the volume in blocks 


+ 12 to +15 


free_ blocks 


B 


Number of unused blocks 


+ 16 to +17 


file_$ys_id 


R 


Operating system ID code 



The VOLUME command takes one input parameter — a pointer to the name of the 
device (dev_name) — and returns information respecting the volume in that device. 

Dev_name points to a string of the form .Dn that is preceded by a length byte. 
The value for n can be from 1 up to the number of Pro DOS block devices in the 
system. The only way to determine the maximum value for n is to call VOLUME 
with consecutive device names until error Sll (invalid device) occurs. 

Vol^name is a 17-byte buffer area in which VOLUME returns a length byte 
followed by the name of the volume. The name of the volume includes a leading 
slash (/). 

The other values returned are as follows: 

total_blocks. The total number of blocks on the volume. 

free _hlocks. The total number of unused blocks on the volume. 

file_stjs_id. The low-order byte of this word indicates the type of operating 
system to which the device belongs. The possible results are as follows: 

• 1 = ProDOS or SOS 

• 2 = DOS 3.3 

• 3 = DOS 3.1 or 3.2 
» 4 = Apple II Pascal 

• 5 = Macintosh (Hat file structure) 
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• 6 = Macintosh (HFS: hierarchical file structure) 

• 7 = Macintosh XL 

• 9 - Apple CP/'M 

All other values are reserved. Version 1.1 of ProDOS 16 recognizes only Pro DOS 
and SOS disks, however (file_sys_id = 1). If it detects another type of disk, it 
returns an error code of $52 (unsupported volume type), 

The other common error codes that VOLUME might return are as follows; 



S2* 



I/O error; this error is reported if there is no disk in a 5'/i-ineh drive. 
No device connected; this error occurs if you do not have a second 5 l A- 
inch drive connected to the drive controller. 
Device not on line; this occurs if there is no disk in a 3'/2-inch drive. 



Manipulating Prefixes 

Earlier in this chapter you saw how useful prefixes can be. ProDOS 16 lets you 
define eight different prefixes, which can be referred to by the prefix designators 
0/, 1/, 2/, 3/, 4/, 5/, 67, and 7/, As explained earlier, the first three prefixes are 
reserved for the system subdirectory i.i),' . the application subdirectory (1/). and the 
library subdirectory (2/), 

The prefixes from 3/ to 7/ are not used in any special way by the operating system, 
so applications can use them to identify any directories they wish. For example, 4/ 
could be a directory containing help files and 5/ could be a directory containing data 
files for an application. 

Use the SET_PREFIX command to assign prefix strings to the eight standard 
prefixes. The parameter table looks like this; 



SET.PREFLX 


(S09) 






Offset 


Symbolic 
Name 


input 

or 
Result 


Description 


+0 to +1 

+ 2 to +5 


prefix_num 
prefix 


1 
1 


Prefix number (0 to 7} 

Pointer to the new prefix string 



Both these parameters are input parameters. The string [jointed to by prefix begins 
with a length byte, which is followed by the ASCII-encoded characters in the 
directory pathname. If the prefix string is not preceded by a slash, the string is 
appended to the current prefix to create the new prefix string. 
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The GET.PREFIX parameter table looks like- this: 



CET^PREFIX sOA 



Input 
Symbolic or 

Offset Name Result Descri ption 

+0 to +1 prefi\_num I Prefix number (0 to 7) 

+2 to +5 prefix R Pointer to prefix name string 



Use GET_PREFIX to determine the current settings of the standard prefixes. It 
returns the result in a buffer pointed to by the prefix parameter. The- result is a 
length byte followed by the prefix name. The name is preceded and followed by 
slashes < "/ '; You must allocate a buffer of 67 bytes to accommodate the largest prefix 
mime that might be returned. 

FILE I/O COMMANDS 

The file I/O commands affect the data portion of a Hie. The two main commands an 
application uses are for reading and writing. Reading, of course, is the transfer of 
data from disk to memory, writing involves a transfer in the opposite direction. 

Positions in the File 

Before the file I/O commands .ire examined, two important concepts — mark and 
EOF — should be mentioned 

The position within a file at which a subsequent read or write operation will take 
place is called the mark position As you access bytes in the file, the mark position 
keeps incrementing, so it is always pointing to the next byte to be accessed. 

When sou open a file prior to reading from it or writing to it, ProDOS 16 sets 
mark to 0. meaning thai subsequent operations will take place at the beginning of 
the file, (The bytes in a file are numbered from 0.) As will be shown later in this 
chapter, it is easy to skip to any other position in the file using the ProDOS 16 
SET.MARK command. 

The other important position parameter is EOF. EOF, which stands for "end-of- 
file," contains the size of the file in bytes, so it can be thought of as a pointer to the 
byte past the last byte in the file. EOF automatically increases as you write data to 
the end of the file. You can increase or decrease EOF explicitly with the SET_EOF 
command. 
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Heading 

To read data From a file, you must perform the following steps: 

1. Open the file 

2. Move the mark position (if necessary) 

3. Adjust newline mode (if necessan I 

4. Road the data 

5. Close the file 

You can read only from a file which is open Opening a file tells FroDOS 16 the 
name of the file you want to deal with and permits it to set up a buffer area it needs 
to manage the How of data to and from the file. To open a file, use the OPEN 
command; it requires the following parameter table: 



OPEN ($10) 



Offset 



+Q to +l 

+ 2 to +5 
+6 to +9 



Symbolic 
Same 



rcf_num 
pathname 
null field 



Input 

or 

Result 



K 

1 

R 



1 iption 



Reference number for the file 
Pointer to the pathname string 
Reserved area for Pro DOS 16 



The only parameter you specify before calling OPEN is the pathname pointer. The 
parameter OPEN returns is ref_num. It is an identifying number for the open file. 
this number is used instead of a pathname by all oilier ProDOS 16 commands 
dealing with open files. You must store rd'.num in the reference number fields of 
the parameter tables for any other such ProDOS 16 commands you will call before 
closing the file. 

ProDOS 16 sets the mark position to when you open a file — the start of the 
file. Before actually reading data from the file, you may want to move to some other 
position. For example, if the file is composed of a series of 50-byte records and you 
want to move directly to record #3 (numbering begins with #0), you would move 
mark to position 150. This is done with the SET,MABK command; its parameter 
table looks like this: 
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SET.MARK 


($16) 






Offset 


Symbolic 
Name 


Input 

or 
Result 


Description 


+0 to + 1 
+2 to +5 


ref_num 

position 


! 
1 


Reference number for the file 
The new mark position 



The ref_num in the SET.MARK parameter table must be the same as the one 
returned when you opened the file whose mark position is being changed. 

Another matter you might want to deal with before reading is to adjust the 
newline character. Thi.s is the character that, when read from a file, will terminate 
a read operation even if the requested number of characters has not been read. If 
you assign the newline character to a carriage return (ASCII $0D), for example, you 
can easily read a text file line by line. 

The command For setting the newline character is NEWLINE, Its parameter 
table looks like this: 



NEWLINE 


($11) 






Offset 


Symbolic 
Name 


Input 

or 

Result 


Description 


+0 to +1 
+2 to +3 
+4 to +5 


ref„num 

enable_inask 
newline_ehar 


I 

1 
1 


Reference number for the file 
Newline enable mask 
Newline character 



A character read from an open file is logically ANDed with the value of enable., 
mask before a comparison with newline_char is made. If the end-of-Iine character 
mighl be a carriage return whose high bit is on or off, use an enable_mask of ffrTF 
and a newline_char of SOD; when vou do so, a read will terminate with SOU or 
S8D. 

Set the enable_mask to $00 to disable the newline feature. 

You are now ready to read information from the file with the READ command. 
The parameter table looks like this: 
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READ ($12) 








Offset 


Symbolic 
Name 


input 

or 

Result 


Description 


+0 to +1 


ref_num 


1 


Reference number tor file 


+2 to +5 


data_ buffer 


I 


Pointer to start of data buffer 


+6 to +9 


request_count 


i 


Number of bytes to read 


+ 10 to + 13 


transfer_count 


R 


Number of bytes actually 
read 



You must specify three types of information in the parameter list: the reference 
number of the file to be read, the starting address of a block of memory where the 
input data will be stored, and the number of bytes to be read. When the operation 
ends, the transfer.count field contains the number of bytes actually read from the 
file. This number will be less than the requested number if the active newline 
character was encountered or if the end of the file was reached, If no characters 
were read at all, the earn' flag is set and the accumulator contains an error code of 
$4C (end-of -file encounters 

As data is read from a file, the mark pointer automatically advances, so there is 
no need to call SET.MARK explicitly after each read. 

When you are all through with a file you should formally close it with the CLOSE 
command. This frees up the memory spaces that ProDOS 16 allocates to the file 
when it is first opened The parameter table for the CLOSE command looks like 
this: 



CLOSE ($14) 



Offset 



+0 to +1 



Symbolic 
Name 



ref_num 



Input 

or 

Result 



Description 



Reference number lor the file 



Once a file is closed, you cannot read from it again until it has been reopened. 

If the ref.num specified in a CLOSE command is $00, all files at or above the 
current file level arc closed. The file level is a number between and 255 that you 
can set using the SET_LEVEL command: 
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SET.LEVEL 


($1A) 






Offset 


Symbolic 
Name 


Input 

or 
Result 


Description 


+G to + 1 


level 


1 


The new file level 



To assign a certain file level to an open file, n.se SET_LEVEL before opening the 
file with OPEN. You cannot change the level of a file after it is open 

If you want to determine the current file level, use GET_LEVEL. Its parameter 
table is the same as that for SET_LEVEL. 

You will not need to bother with file levels often. They become important when 
you want to manage EXEC! files properly. EXEC files are files to which the operating 
system looks for input instead of the keyboard. If you switch to a higher file level 
after opening an EXEC file, subsequent CLOSE operations will not close the EXEC 
file. 

The subroutine in listing 10—1 shows how to use many of the Pro DOS 16 com- 
mands just described. It opens a textfilc. disables uewline mode, determines the 
file size with GET_EOF. uses the Memory Manager to allocate a block of that size, 
reads the file into memory, and then closes the file. 



Writing to a File 

The procedure for writing to a file (see listing 10-2) is similar to the one for reading 
from a file. Before actually writing, yon must open the file and. if necessary, position 
me mark pointer. To perform the write operation, use the WHITE command; its 
parameter table looks like this: 



WRITE 


(S13) 








Offset 




Symbolic 

Name 


Input 

or 

Result 


Description 


+0 to + 1 




ref_num 


I 


Reference number for the file 


+ 2 to +5 




data, buffer 


I 


Pointer to start of data buffer 


+6 to +9 




request_count 


1 


Number of bytes to write 


+ 10 to +13 


transfer count 


R 


Number of bytes actually written 
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The data.buffer field points to a block of data you wish to write to the file; the size 
of this block is given by request, count The transfer_count field returns the actual 
number of bytes written to the disk It will be less than the requested number if 
the (I ime full during the write operation or if a disk error occurred. 

One common form of write operation is an append. This is the process of ex- 
panding the size of a file by adding data to it. The following subroutine shows how 
to append data to an existing file: 





_0PEN OpenParms 




LDA ref_num 




5TA ref_num1 




STA ref_num2 




STA ref_num3 




_GET_EQF EOFParms 




_SET_MARK EOFParms 




_WR1TE WnteParms 




_CLOSE CloseParms 




RTS 


OpenPa rms 


ANOP 


r e f _ ft u m 


DS 2 




DC I 4' File-Name' 




DS 4 


EfJFParms 


ANOP 


ref _num1 


DS 2 


pos 1 1 ion 


DS 4 


Wr i t eParms 


ANQP 


ref _num2 


DS 2 


da ta_buf f 


DC 14 'Buffer' 


request 


DC 14 '51 2' 


transfer 


DS 4 



Open the file 

Get reference number 

and store it in other 

parameter lists. 

Get the file size 
Set mark to end of file 
Write data to file 
Close the file 



;Reference number 
'.Pointer to pathname 
".Handle to I/O buffer 



; Position in file 



«, Buffer containing the data 
-.Number of bytes to write 



CloseParms ANOP 
ref num3 DS 2 



FileName STR • MYF I LE .DEMO ' 

Buffer DS 51 2 



; Name of file 
; Data to write 



This example uses one command that has not been discussed yet: GET_EOF. GET. 
EOF returns the size of the file, in bytes, in a four-byte field in its parameter table. 
To do an append, all you must do is set the mark position to this value before 
writing to the file, as shown in the example above. 
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The complete parameter table for GET_EOF looks like this: 



CET.EOF 


:.SI9 






Offset 


Symbolic 

Name 


Input 

or 

Result 


Description 


+0 to +1 
+ 2 to +5 


re f_ mini 
eof 


1 
i; 


Reference number for the file 
The end-of-file position 



Two other commands you may use in conjunction with write operations are GET_ 
MARK and SET_EOF, Here are their parameter tables: 



CET.MARK 


(*1 


7) 






Offset 




Symbol it- 
Name 


Input 

or 

Remit 


Description 


+0 to +1 

+2 to +5 




ref_nnm 

position 


I 
B 


1 iiue number for the file 
The current mark position 



SET, EOF ;$LSi 



Input 
Symbolic or 
Offset Name Result Description 

+0 to +1 ref.num 1 Reference number for the Hie 

+ 2 to +5 eof I The new end-of-file position 
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CET_MARK returns the current value of the mark pointer .and SET.EOF sets the 
size of the file to the- value passed in its parameter table. Von will use both of them 
in situations in which you want to eliminate everything in a file past the current 
mark position. Here is the subroutine to use; 

_GCT_MARK MarkParms ;Get current mark position 

_SET_EQT MarkParms ; and make it the new file size. 

RTS 



Such an operation is often performed in word processing programs when a file is 
loaded into memory, modified, and saved to disk under the same name. If the 
modified file is shorter than the original, and yon do not set the new EOF position 
after the write, the file will still include the tail end of the original file. 

When you write data to a file, the data actually is not saved to disk right away. 
Instead, it is placed in a Pro DOS I/O buffer that is transferred to disk only when it 
fills up or when the file is closed. You can force ProDOS to empty the I/O buffer 
at any time using the FLUSH command: 



FLUSH ($15) 



Input 
Symbolic or 

Offset Name Result Description 



+ () to +1 ref_num I Reference number for the file 



Calling FLUSH minimizes the risk of losing data if the system crashes or the power 
goes off before the file you are writing to is closed. It does slow down the effective 
execution speed of a program, however, so it is not used often. 
Note that if rcfjium is $00, all open files are flushed. 



DEVICE-MANAGEMENT COMMANDS 

The device-management commands are for dealing with block devices themselves, 
not the individual files they contain. They perform such chores as low-level block 
I/O and disk formatting. 
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Formatting 

Disks must be formatted with thr FORMAT command before you can save files to 
them. Formatting is actually a two-step process: 



1. Conditioning the magnetic surface of the disk 

2. Writing boot code, directory, and block usage information on the disk in the 
manner dictated by the operating system 



Because formatting permanently erases any information on a disk, you should ask 
the user to verify such an operation if the disk is not blank. 

The structure of the parameter table for FORMAT is as follows: 



FORMAT 


($24) 










input 






St/mboltc 


or 




Offset 


Name 


Result 


Description 


+0 to +3 


dev^name 


1 


Pointer to the device name string 


+4 to +7 


vol_name 


1 


Pointer to the volume name 
string 


+8 to +9 


file_sys_id 


I 


Operating system ID code 



The dev_name parameter is a pointer to the device name string (the string will be 
.Dl, ,D2, and so on). The volume name string can be up to 16 characters long; it 
must adhere to the ProDOS file-naming rules and must include a leading slash {/). 

The meaning of the file_sys_id field was explained earlier in connection with the 
VOLUME command. It describes the operating system used by the command. In 
this ease, it tells FORMAT the technique to use to lay out the disk directory 
information on the volume. 

Keep in mind that early versions of ProDOS 16 supported die formatting of 
ProDOS disks only (file_sys_id = $01). You will get an error code of $5D (operating 
system not supported) if you set file_sys_id to anything other than SOL 
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Accessing Specific Blocks 

If you are writing a utility program such as a disk copier or a file undeleter, you 
will probably want to read and write specific blocks on a disk. To do tliis, use the 
READ.BLOCK and WRITE.BLOCK commands. They both use the same type of 
parameter block; 



READ.BLOCK 


($22) 






Offset 


Symbolic 
Name 


Input 

or 
Result 


Description 


+0to +1 

+ 2 to +5 
+6 to +9 


dv\ _num 
data_buffer 
block num 


1 
I 
I 


Device reference number 
Pointer to the read buffer 
Block number to read in 



WRITE.BLOCK ($23) 






Offset 


Symbolic 
Name 


Input 

or 

Result 


Description 


+GtG +1 

+2 to +5 
+6 to +9 


dev_num 
data_buffer 
block num 


1 

I 

r 


Device reference number 

Pointer to write buffer 

Block number to be written to 



the memory blocks pointed to by data_buffer in each case are exactly 512 bytes 
long (tlie size of a disk block). The block numbers on a disk range from to an 
upper limit that depends on the nature of the disk device. Use the VOLUME 
command to determine the size of a disk volume in blocks. 

The dcv_num parameter needed by both READ.BLOCK and WRITE.BLOCK 
is a device reference number (.Dl, D2, and so on), not the device name. To 
determine the reference number for a given device name, use the GET_DEV_ 
NUM command; its parameter table is as follows: 



356 The ProDOS 16 Operating System 



GET_DEV_NUM ($20) 



Input 
Symbolic or 
Offset Name Result Description 

+0 to +3 dev_name I Pointer to the device name string 

+ 4 bo +5 dev.num R Device reference number 

When ProDOS first starts up, it scans the system for block devices and assigns them 
unique device reference numbers. These numbers are consecutive integers begin- 
ning with 1, This identification system is quite different from that used in ProDOS 
8 in which devices are identified by slot/drive combinations. 

Last Device Accessed 

ProDOS 16 has a command lor determining the reference number of the last device 
accessed by a read or write command. This is the GET_LAST_DEY command: 

GET_LAST_DEV ($21) 



Input 
Symbolic or 
Offset Name Result Description 

+0to+I dev.num R Device reference number 

If GET_LA5T_DEV is unable to determine what the last device was, it returns an 
error code of $60. 

OPERATING-ENVIRONMENT COMMANDS 

You can use the operating environment commands to determine the name of the 
currently running application, the name of the boot volume, and the ProDOS 16 
version number. These commands also include the important QUIT command, 
which you will use to transfer control from one application to another. 

Status Commands 

It is often convenient For a program to know its own name. It may need to know 
this information so it can transfer a copy of itself to a RAM disk, for example. Instead 
of using a specific name, you should use the GET_\AME command, just in case 
the user has renamed the program, 

Operating-environment Commands 357 



The parameter table for (Ml NAME looks like this ; 



GET.NAME 


($27) 






Offset 


Symbolic 
Verne 


Input 

or 

Result 


Description 


+0 to +3 


data_buher 


R 


Pointer to application name string 



The space for (lit- naint- should be 16 bytes long so that there will be room for the 
longest possible filename and the preceding length byte. 

Notice that CET_NAME returns the filename only. The subdirectory in which 
it resides is given by the 1 prefix. Use GET_PBEF1X to determine what this prefix 
is. 

To access files on the boot disk, you can specify a pathname constructed by adding 
the "*/" prefix designator to a partial pathname. IT you need to know the actual 
name of the boot disk, use the GET_BOOT_VOL command. Here is its parameter 
table: 



GET. ROOT. VOL (928) 



Offset 



+ to +3 



Symbolic 
Same 



data_burTer 



Input 

QT 

Result 



H 



Description 



Pointer to the volume name string 



GET_BOOT„VOL returns a name which begins and ends with a slash, so the 
buffer space should be IS bytes long. 
There is also a (.El _V ERSION command lor determining the version number 
of ProDOS. An application should cheek the version number if the program works 
only with certain versions of ProDOS, Here is the parameter table: 



358 The ProDOS 16 Operating System 



GET. VERSION 


(S2A) 






Offset 


Symbolic 
Name 


Input 

or 
Result 


Description 


+o to + 1 


version 


R 


ProDOS 16 version number 



The low-order byte of the version word represents the minor release number and 
the high-order byte represents the major release version. Version 2.1, for example, 
would be stored as $0201. If the high-order bit of the result is 1, it is a prototype 

version. 

The QUIT Command 

ProDOS 16 has a single command yon can use to leave doc application and transfer 
control to another: QUIT. With it you can either run a specific program or return 
control to the program whose UserlD is on the top of a Quit Return Stack. 

The Quit Return Stack is where an application places its UserlD if it wishes to 
regain control the next time an application quits without specifying the pathname 
of the next application to run. The availability of a Quit Return Stack makes it easy 
for a supervisor) program to execute subsidiary programs so that control always 
eventually returns to the original program. In fact, the GS program launcher always 
pushes its LserlD on the Quit Return Stack before Launching an application. If it 
did not, you would not return to it when an application ended. 

Use the following parameter table with the Quit command: 



QUIT ($29) 



Offset 



Symbolic 
Name 



Input 

or 
Result 



Description 



+0 to +3 
+ 4 to +5 



pathname 

flags 



iier to next pathname 

Re I urn .'Res tart flags 



The pathname parameter points to the pathname of a ProDOS 16 or ProDOS 8 
system program. As usual, the pathname begins with a length byte The current 
application will load and run this program when you call the QUIT command. 
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II tin* pathname pointer is 0, and the Quit Return Stack is not empty, ProDOS 
16 pulls a User ID from the Quit Return Stack and executes the program with that 
ID. If the Quit Return Stack is empty, ProDOS 16 calls up a standard dispatcher 
subroutine that lets you type in the name of the next system program to run, reboot 
the disk, or run the SYSTEM/START program. 

Only the two high-order bits of the Hags parameter are significant. If bit 15 is 1, 
ProDOS places the current application's UserlD on the Quit Return Stack before 
passing control to the application described by the pathname pointer. This means 
that control eventually will return to the current application as later programs quit 
with a pathname parameter. II bit 15 is 0, nothing is placed on the Quit Return 
Stack. 

If bit 14 of the flags is 1, the calling program is capable of being restarted without 
being reloaded from disk. If control returns to it. it will not be loaded from disk 
unless it has been purged from memory by the Memory Manager. 

The QUIT command never returns control to the application. II an error occurs, 
an interactive dialog box appears on the screen with the error number on the last 
line in the box. 

INTERRUPT-CQNTROL COMMANDS 

ProDOS 16 has a 16-entry internal table thai contains the addresses of the subrou- 
tines it calls when it receives word that a 65816 IRQ interrupt signal has occurred. 
It calls each subroutine in sequence until one of them claims the interrupt (by 
clearing the carry flag). If the interrupt is not claimed, a fatal system error occurs. 
To use an interrupting device with ProDOS 16, begin by loading its interrupt- 
handling subroutine into memory. The characteristics of such a subroutine are as 
follows: 

It must be able to determine if the source of the interrupt is the device for 
which it is designed. 

If its device is not the source of the interrupt, it must set the earn' flag with 
SEC 

If its device is the source of the interrupt, it must handle the interrupt by 
clearing the interrupt condition (usually by reading the device status], perform- 
ing the necessary I/O operation, and then clearing the cany flag with CLC. 

It must end with an RTL instruction. 

The interrupt handler does not have to preserve the status of the A t X, or Y registers 
since ProDOS restores and saves them. 

Next, install the interrupt handler with the ALLOCJNTERRUPT command. 
The last step is to enable interrupts from the external device. 

Here is the structure of the ALLOCJNTERRUPT parameter table: 
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ALLOCJNTERRUPT ($31) 



Offset 



+0to +1 
+2 to +5 



Symbolic 
Name 



int_num 
mtcode 



input 

or 

Result 



H 

I 



Descri ption 



Interrupt handler reference number 
Pointer to interrupt handler 



In this table, int.num is the reference number returned by ALLOC_INTERRUPT. 
Int.code is a pointer to the start of the code for the interrupt handler. 

Note that if the interrupt handler uses system resources that may be busy (usually 
ProDOS 16 itself), it should first check the Scheduler's busy Hag at $E100FF. If 
this Hag is non-zero, handling of the interrupt must be deferred by adding a task to 
the Scheduler's queue with the SchAddTask function: 



PHA 

PushPtr TheHandlei* 

_SchAddTaslc 

PLA 



; 5 p a c e for result 

;SubrouttTie for Scheduler to call 

; pop Boolean 



The Boolean result is true if the task was added to the queue. 

Handlelnt is the address of a subroutine (ending in RTL) inside the interrupt 
handler that includes the call to the system resource. When the busy flag is turned 
off by the interrupted program, the Scheduler automatically calls the Handle] nt 
subroutine to complete processing of the interrupt. (If you don't check the busy flat; 
and ProDOS is busy, you will get an error code of $07 when you attempt to use a 
ProDOS command.! 

To remove an entry from the interrupt handler table, use DEALLOCJNTER- 
RUFT, but only after you have told the external device to stop generating interrupts. 

DEALLOCJNTERRUFT uses this parameter table; 



DE ALLOCJNTERRUPT ($32) 



Offset 



+0 to +1 



Symbolic 

Xamr 



intnum 



Input 

or 

Result 



Description 



Interrupt handler reference number 



The int.num you pass to DEALLOC.INTERBUPT is the number returned by 
ALLOC JNTERRUFT when you installed the handler. 
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STANDARD FILE OPERATIONS 

Two file-related operations are SO common that Apple Computer. Iw has developed 
(! entire tool set to support them. The first operation is for displaying a list ol disk 
files SO that one can be easily selected- The second one is lor requesting the name 
for a file that is to be saved to disk 

The (unctions used to perform these operations form part of the Standard File 
Operations tool set (tool set 23), These functions are called in the same way as any 
other tool set function They are not ProDOS 16 commands, so do not call them 
with the standard ProDOS 16 calling sequence. 

The Standard File Operations start-up function is SFStartup. Call it once at the 
beginning of a program that uses the tool set 

PushWord MylD ;ID of program 

PushWord DPAddr ;Address of one page m bank 100 

_5FStartup 

As you can see. SFStartup requires a direct page in hank 800 to work with. 

The shut-down function is SFShutDown It requires no input parameters and 
does not return results. 

SFGetFile 

The file-selection function. SFGetFile, was used in the program in listing 10- 1 It 
creates a dialog box similar to the one shown in figure 10-2. At the top of the left 
half of this box is the name of the current directory; below this name is a window 
containing an alphabetical list of files in thai directory, each preceded by an icon 
indicating the general file type. The window has a vertical scroll bar that can be 
used to move any portion of the Its! of hies into view. On the right side are four 
buttons labeled Open. Close, Cancel, and Disk. 

You can select a file by highlighting its name (by clicking on it) and then clicking 
the Open button, or simply by double-clicking on its name. You can also highlight 
a name bj typing the first character of the name; if there is more than one name 
beginning with the character, the first one is highlighted. The up- and down-arrow 
keys can be used to move through the list of files one entry at a time 

If the selected file is a subdirectory (marked by a file-folder icon), the name of 
the current directory changes and a list of the files in the new, lower-level sub- 
directory' is shown. If the file is not a subdirectory, the dialog box disappears from 
the screen and the program can deal with the selected file. 

It is also possible to display and select file* in higher-level subdirectories or on 
other disks. To move to the next higher subdirectory (closer to the volume directory) 
click once on the prefix name shown above the file window, type (he Esc key. Or 
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Figure ltt-2. The- SFGetFile Dialog Bra 



Select a file to view: 
S /flpw/W/ 



D M16.Sound 
D M1& Stdfile 

D Hl&.Texttool 

D motility 
□ Ml&.Window 
DHg 
D Ma.Hacs 
D Standard Asm 







( Disk J 



[ Close J 
( Cancel ") 



click the Close button. Subsequent clicks will eventually take yon right up to the 
volume directory, To display the files on another disk, click the Disk button until a 
list of the disk's files appears in the file window, 

Notice that the first time you click the Disk tuition, the disk in the current drive 
is examined to see if you have removed it and inserted another disk: if you have 
inserted a new disk, the files on it are shown, If you have not, the files on the disk 
in the next drive are shown. Subsequent clicks will bring you to the other drives in 
the system, 

SFGetFilc requires six input parameters, including a pointer to a parameter list 
called a reply record, When SFGetFile ends, the reply record can be read to 
determine which file, if any, was selected. Here is how to call SFGetFile: 



PushWord UhereX 
PushWord WhereY 
PushPtr Prompt 
PushPtr FilterPrc 
PushPtr TypeList 
PushPtr ReplyRec 
_SFGetFi le 
RTS 



;Horizontal position of box 
•.Vertical position of box 
; Pointer to prompt string 
; Pointer to filter procedure 
*, Pointer to file type list 
'.Pointer to reply record 
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ReplyRec 


ANQP 




Good 


D5 


2 


Fa letype 


D5 


d 


Auxtype 


DS 


2 


F 1 J enarne 


D5 


16 


Pathname 


DS 


129 


TypeList 


DC 


I 1 • 2 < 




DC 


n '$04' 




DC 


I 1 • «B0 ' 



; Standard repiy record 

; True = open j False = cancel 

;File type code 

{Auxiliary type code 

; Fi 1 e name s t r i ng 

; Full pathname string 

•.{byte, not word) 
;Text file 
{Source file 



Prompt STR 



'Select a file: 1 ; Prompting string 



The first two parameters represent the coordinate of the top left-hand corner of the 
dialog box. The Prompt string is displayed inside the box, just above the file window, 
and is supposed to be a short message to the user. 

Filter Procedure 

FilterProc is a subroutine that SFGetFile calls to determine how to display the 
name of a file or whether to display it at all. FilterProc returns one of three result 
codes, which SFGetFile examines to make the determination: 

Do not display the filename 

1 Display the filename in dimmed text 

2 Display the filename in standard text 

Filenames which appear in dimmed text in an SFGetFile dialog box cannot be 
selected by the user. 

If the pointer to FilterProc is 0\ SFGetFile does not call a filter procedure, and 
all filenames are displayed and selectable. 

SFGetFile calls the filter procedure in much the same way an application calls a 
tool set function: it first pushes space for the result code (a word) on the stack, and 
then pushes a pointer to the file's 39-byte directory entry; finally, it calls the filter 
procedure with a JSL instruction, 

A filter procedure, which you must write yourself, should first decide how the 
filename is to be displayed. The decision is usually based on the value of the file 
type code or die filename, both of which are stored in the directory entry record 
whose address is passed as a parameter. The structure of a directory entry record 
is shown in table 10-4. 

After deciding how to display the filename, the filter procedure must place the 
appropriate result code in the space reserved for the result on the stack. The address 
of this space will be the value of the stack pointer plus 8 if the stack pointer has not 
changed since the procedure was entered. 
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Table 10-4: The Formal of a ProDOS Directory Entry 



Offset 




Meaning 


+ (low four 


bits) 


Length of filename 


+0 (hi^h foui 


bits) 


Storage type rode 


+ 1 to + 15 




Filename character string 


+ 16 




File type eode 


+ 17 to +18 




Block number of files index block 


+ 19lo +20 




File size (in blocks) 


+ 21 to +23 




EOF position 


+ 24 to +25 




Creation date 


+ 26 to +27 




Creation time 


+ 28 




Version of ProDOS which created the file 


+ 29 




Lowest version of ProDOS that can use file 


+30 




Access code 


+31 to +32 




Auxiliary type code 


+33 to +34 




Modification date 


+35 to +36 




Modification time 


+ 37 to +38 




Block number of first subdirectory' block 



Finally, the procedure must remove the input parameter from the stack by moving 
the three-byte return address on the top of the stack up by four bytes and adding 
4 to the stack pointer. When the procedure ends with RTL, the result is on the top 
of the stack, ready to be popped off by SFGetFile. 

Here is an example of a filter procedure you could use to prevent files with a file 
type eode of $FF (ProDOS 8 system programs) from being displayed: 

■, Save current d . p . 

; Stack pointer to accumulator 

;Align d.p. with stack 

•.Offset to file type code 
;Acce53 the file type code 
; 1 so late the byte 
;ProD0S 8 system program? 
;No, so branch 
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PHD 




TSC 




TCD 




LDY 


#16 


LDA 


[$61 ,Y 


AND 


#$00FF 


CMP 


#*FF 


BNE 


SetCode 



LDA #0 

BRA SaveCode 



I o don ' t incl ude 



SetCode LDA #2 



SaveCode 


PLD 










STA 


Li 


,S 






LDA 


2 


,S 






STA 


£ 


,s 






LDA 


1 


,s 






STA 


5 


»s 






TSC 










CLC 










ADC 


#4 






TCS 










RTL 







■» 2 = include/selectable 

^Restore d;rect page 
•»Save the result 

;Move the 3-byte return 

; address up by 4 bytes. 

; (it's now at SP + 1 to SP + 3) 



;Add 4 to the stack pointer 



', (Don' t use RTS! } 

This procedure illustrates the standard technique for dealing with pointers that are 
passed on the stack. After pushing the current value of the* direct page register, this 
routine defines a new direct page that is aligned with the top of the stack. This 
means the pointer to the directory entry is at position $06 in the direct page (above 
the two bytes pushed by PHD and the three bytes pushed by the initial JSL to the 
procedure); because the pointer is now in direct page, you can access the elements 
of the directory entry with the long indexed indirect addressing mode. 

There are two other important matters related to the use of a filter procedure. 
First, you will not be able to interfere with the display of a subdirectory file; such 
files are always shown and are selectable. Second, SFGetFile allows a filter proce- 
dure to change the contents of the A, X, and Y registers but not the direct page or 
data bank registers. If you must change the direct page (as in the above example) 
or the data bank, save it on the stack first and restore it just before the procedure 
ends. 



Type List 

TypeList is a table containing a list of file type codes, preceded by a count byte; 
each file type code occupies one byte in the table, If the filter procedure pointer is 
0, SFGetFile displays the name of a file only if the file's type code is in this list. If 
a filter procedure is defined, filenames referred to in the type list are passed to it 
for further analysis 

For example, if you want to display only files containing readable text, use the 
following TypeList table: 



TypeL i s t 



DC II '2' 
DC H'04' 
DC H'BG' 



; Two entries 
;Textfile (TXT) 
;APW source file 



(SRC) 
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Directory files are always displayed, even if they are not explicitly included in the 
Type Li st table. 

If the pointer to a TypeList table is 0. all types of files will he displayed unless 
some are restricted by a filter procedure. 

You should use a TypeList whenever the list of file type codes voti want to permit 
IS relative!) short. If you are trying to prevent the display of only a lew types of 
files, it is more convenient to use a filter procedure instead of a Typelist. You will 
also want to use a filter procedure if you wish to allow restricted file names to he 
displayed, but not selectable. The filter procedure in listing 10-3 is a., example of 
sue li a filter. 

Reply Record 

When the user clicks the Open or Cancel button in the dialog box, control returns 
to the application and the results are in the repl) record. The first field. Ootid is a 
Boolean value indicating which button was pressed; it b true (non-zero) if it was 
Open or false (zero) if it was Cancel, 

The remaining fields have meaning only if Good is true. Filetvpe and Auxtype 
hold the file type code and the auxiliary type code of the selected file, respectively 
The name ol the hie is stored at Filename and the full pathname of the file is stored 
at Pathname. In each case, the name string i- preceded by a length byte. 

If Open is pressed, SFGetFile sets prefix W (the ddai.lt directorv) to 'the directorv 
in which the selected file resides. Prefix 0/ does not change if Cancel is pressed 



SFPutFile 



The 



hmc-tioii to use when you want to request that a filename be entered is 
St Pull- ile see listing 10-2). This function generates a dialog box similar to the one 
shown in figure 10-3. Like a SFGetFile box, this dialog box contains a directorv 
window on the left side, but all non-directory files are dimmed. What you are 
supposed to do is move to the correct subdirectory of the correct disk using the 
Open. Close, and Disk buttons (much as you would If you were using SFGetFile). 
Next, you type in the name of the file to be saved in the text-entry rectangle in the 
lower left corner of the box. This is an EdltLine dialog item, so you can use all the 
standard editing techniques to enter a name. When the SFPutFile dialog first 
appears, a default filename is highlighted. 

If is also possible to create a new subdirectory before selecting a filename. To do 
this, type in a subdirectory name and then click the New Folder button 

Here is how to call SFPutFile: 



PushWord WhereX 
PushWord WhereY 
PuahPtr Prompt 
PushPtr OngName 



•.Horizontal position of box 
;Vertical position of box 
;Pointer to prompt string 
-.Pointer to default filename 
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Figure 10-3. The SFPutFilr Dialog Box 



© /Apw/ 

Free: 106k out of 1024k. 



I_J System 
Q Sijstesp 
CD Utilities 

D tt.Tso 



O 



Enter a name for the file: 



c 



I) 



'TEMPORflRV.TnT 



(New Folder ) 
t Close ) 



Save 



( Cancel "") 



PushWard MaxLen 
PushPLr ReplyRec 
.SFPutFile 
RTS 



* t Maximum length of response 
•, Pointer to reply record 



Many of the same types of parameters used by SFCetFile are also used by 
SFPutFile. The new parameters used by SFPutFilc are OrigName, a pointer to the 
default filename, and MaxLen, the maximum length of the filename to be entered. 
In most circumstances, you will want to set MaxLen to IS, the maximum length of 
a ProDOS filename. 

If the name selected (by clicking the Save button) is already being used as a 
subdirectory name, SFPutFile displays an "I Can't Destroy a Director}" dialog box 
with an OK button. Another name can he selected after the OK button is clicked 
If the name is already being used by a normal data file, SFPutFile displays a "Replace 
Existing Fill v dialog box with Yes and No buttons. If No is clicked, another name 
can be selected; if Yes is clicked, SFPutFile ends. 

SFPutFile also ends when the Cancel button is clicked or when a unique filename 
is entered and the Save button is clicked. The Good field in the reply record is false 
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if the Cancel button was pressed; otherwise, it is true. If a name was entered, it is 
returned in the filename field, and the pathname field contains the complete path- 
name. In addition, the selected directory is assigned to prefix 0/. 



REFERENCE SECTION 

Table R10-1: The Parameter Tables for the FroPOS 16 Commands 

NOTE: In these tables, an Input (I) is a parameter that mast be provided before using the command. 
A Result (Rl is a parameter returned by the command- If the Result is a string, you must allocate a 
space for the string that will be returned and provide a pointer to it 



ALLOC .INTERRUPT ($31) 

S ijmbolic 

Offset Name 


Input 

or 

Remit 


Description 


+0 to +1 

+2 to + 5 


int_num 

int_code 


B 

I 


Interrupt handler reference number 
Pointer to interrupt handler 


c:hanc;e_path <$04) 

Symbolic 
Offset Name 


Input 

or 
Result 


Description 


+ Gto +3 

+ -J to +7 


pathname 
new_pathname 


1 
I 


Pointer to the pathname string 
Pointer to the new pathname string 


CLEAR.BACKUP.BIT (SOB) 

Symbolic 

Offset Name 


Input 

or 

Result 


Description 


+ to +3 


pathname 


I 


Pointer to the pathname string 
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CLOSE (SI 4) 



Offset 



Symbolic 
Name 



Input 

or 

Result 



Description 



+ to +1 



refnum 



Reference number for the file 



CREATE ($01) 

Symbolic 
Offset Name 



DEALLOCJNTERRUPT (832) 

Symbolic 
Offset Name 



Input 

or 

Result 



+0 to +3 


pathname 


I 


+ 4 to +5 


access 


[ 


+6 to + 7 


filc_type 


I 


+8 to +11 


aux_type 


I 


+ 12 to +13 


storage.typc 


I 


+ 14 to +15 


ereate_date 


I 


+ 16 to +17 


create, time 


1 



Description 



+0to +1 



intiHim 



Input 

or 

Result 

I 



Pointer to the pathname string 

Access code 

File type code 

Auxiliary type code 

Storage type code 

Creation date 

Creation time 



Description 



Interrupt handler reference number 



DESTROY (S02) 



Offset 



Symbolic 
Name 



Input 

or 

Remit 



Description 



+0 to +3 



pathname 



[ 



Pointer to the pathname string 
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FLUSH ($15) 
Offset 


Symbolic 

Same 


Input 

or 

Result 


Description 


+0 to + 1 


ref.num 


1 


Reference number for the file 


FORMAT ($24) 

Symbolic 
Offset Name 


Input 

or 

Result 


Description 


+0 to +3 
+4 to +7 
+8 to +9 


dev_name 

vol_name 
filc_.sys_id 


1 
1 
I 


Pointer to the device name string 
Pointer to the volume name string 
Operating system ID code 


GET_BOOT_VOL ($28) 

Symbolic 
Offset Name 


Input 

or 

Result 


Description 


+0 to +3 


data.huffer 


H 


Pointer to the volume name string 


GET_DEV_NUM ($20) 

Symbolic 
Offset Name 


Input 

or 

Result 


Description 


+ to +3 

+ 4 to +5 


dev_jiame 
dev_innri 


I 
R 


Pointer to the device name string 
Device reference number 
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GET^EOF ($19) 

Symbolic 
Offset Name 

+0 to +1 ref_num 

+2 to +5 eof 



Input 

or 

Remit 



Description 



I Reference number for the file 

R The end-of-file position 



GET_FILE_ 

Offset 


INFO ($06) 

Symbolic 
Name 


Input 

or 

Result 


Description 


+0 to +3 


pathname 


1 


Pointer to the pathname string 


+ 4 to +5 


access 


B 


Access code 


+6 to +7 


file, type 


R 


File type cork- 


+ 8 to +11 


aux_type 


R 


Auxiliary type code (*) 


+ 12 to +13 


st» rage _ type 


R 


Storage type code 


+ 14 to +15 


create _date 


R 


Creation date 


+ 16 to +17 


create^tirne 


R 


Creation time 


+ 18 to +19 


rnod__date 


H 


Modification date 


+ 20 to +21 


mod_time 


B 


Modification time 


+22 to +25 


blocks_used 


R 


Blocks used by the file 



(*) For a volutin' directory; file, this field becomes total_bbcks (the number of blocks on the volume). 
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GET_LAST_DEV ($21 1 

Symbolic 
Offset Name 


Input 

ur 

Result 


Description 


+0 to +1 devjnum 


R 


Device reference number 


GET. LEVEL. IB 

Symbolic 
Offset Name 


Input 

or 

Result 


Description 


+0 to + 1 level 


R 


The current file level 


GET.MARK ($17) 

Symbolic 
Offset Name 


Input 

or 

Result 


Description 


+ to + 1 ref_num 
+ 2 to +r> position 


I 
K 


Reference number for the file 
The current mark position 



GET.NAME 4$27) 

Symbolic 
Offset Name 



Input 

or 

Result 



Description 



+0to +3 



data_ buffer 



K 



Pointer to application name string 
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GET. PRE FIX tSOA) 










Input 






Symbolic 


or 




Offset 


Name 


Result 


Description 


+ to +1 


pre fix _n um 


I 


Prefix number (0 to 7) 


+ 2 to +5 


prefix 


R 


Pointer to prefix name stunt; 


GET_VERSION (*2A) 










Input 






Symbolic 


or 




Offset 


Name 


Result 


Description 


+0 to +1 


version 


R 


ProDOS 16 version number 


NEWLINE ($11) 










Input 






Si/mi 


or 




Offset 


Name 


Result 


Description 


+0 to +1 


ref_num 


1 


Reference number for the file 


+2 to +3 


enahle_ina.sk 


I 


Newline enable mask 


+ 4 to +5 


newline_char 


1 


Nrwline character 


OPEN ($10) 




Input 






S y in holic 


or 




Offset 


Name 


Result 


Description 


+ to +1 


rei_num 


R 


Reference number tor the file 


+ 2 to +5 


pathname 


I 


Pointer to the pathname string 


+ 6 to +9 


null, field 


K 


Reserved area for ProDOS 16 
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QUIT ($29) 
Offset 


Symbolic 
Name 


Input 

or 

Result 


Description 


+0 to +3 

+4 to +5 


pathname 
flags 


1 
1 


Pointer to next pathname 
Return/Restart flags 


READ ($12) 
Offset 


Symbolic 
Name 


Input 

or 

Result 


Description 


+0 to + 1 

+2 to +5 
+6 to +9 
+ 10 to +13 


ref_num 
data_ buffer 
request.count 
transfer_count 


I 
T 

I 
II 


Reference number for file 
Pointer to start of data buffer 
Number of bytes to read 
Number of bytes aetually read 


READ.BLOCK ($22) 

Symbolic 

Offset Name 


Input 

or 

Result 


Description 



+0 to +1 dev_num 

+2 to +5 data_buffer 

+6 to +9 bloeknum 



I Device reference number 

I Pointer to the read buffer 

[ Block number to read in 
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SET.EOF ($18) 

Symbolic 
Offset Name 


Input 

or 

Result 


Description 


+ to +1 
+2 to +5 


reflnurn 
eof 


I 

I 


Reference number for the file 
The new end-of-file position 


SETJF1LE, 

Offset 
+0 to +3 

+4 to +5 

+6 to +7 
+8 to + 1 1 


.INFO ($05) 

Symbolic 
Name 

pathname 

access 

file_typc 

aux_t>pc 


Input 

or 
Result 

I 
I 

I 
1 


Description 


Pointer to the pathname string 
Access code 
File type code 
Auxiliary type code 



+ 12 to +13 {not used} 
+ 14 to +15 create 



+ 16 to +17 ereate_timc 
+18 to +19 mod_date 
+ 20 to +21 mod time 



I Creation date 

1 Creation time 

I Modification date 

Modification time 



SET.LEVEL (S1A) 
Offset 



Symbolic 
Name 



Input 

or 

Result Description 



+ to +1 



level 



The new file level 
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SET.MARK ($16) 
Offset 



Symbolic 
Name 



+0 to +1 nefj&um 

+ 2 to +5 position 



Input 

or 

Result 



Description 



Reference number for the file 
The new mark position 



SET.PREF1X {$09) 



Offse± 



Symbolic 
Name 



Input 

or 

Result 



+0 to + 1 prefix_iium I 

+2 to +5 prefix I 



Description 



Prefix number (0 to 7) 

Pointer to the new prefix string 



Symbolic 
Same 



VOLUME ($08) 

Offset 

+0 to +3 dev_name 

+4 to + 7 vol _ name 

+8 to +11 tolal .blocks 

+ 12 to +15 free_blocks 

+ 16 to +17 Rle^sysjd 



Input 

or 

Result 



Description 



Pointer to the device name string 
Pointer to the volume name string 
Size of the volume in blocks 
Number of unused blocks 
Operating system ID code 
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WRITE ($13) 
Offset 


Symbolic 
Name 


Input 
CM 

Result 


Description 


+0 to +1 

+2 to +5 
+6 to +9 
+ 10 to + 13 


ref_num 
data_bufter 
request_count 
transfer_coimt 


1 
1 
1 

K 


Reference number for the File 

Pointer to start of data buffer 
Number of bytes to write 

Number of bytes actually written 


WRTTE.BLOCK ($23) 

Symbolic 
Offset Name 


Input 

or 

Result 


Description 


+0 to 4- 1 
+2 to +5 

+6 to +9 


de\_num 

data_bufFer 

block_num 


I 
1 
I 


Device reference number 

Pointer to write buffer 

Block number to be written to 



Table R10-2: Pro DOS 16 Error Codes 



llrror 

Number 



Description 



$00 

$01 

$07 

$10 

$11 



No error occurred. 

The ProDOS command number is invalid. 

ProDOS i$ busy. This error might occur if you try to use ProDOS 
commands Irom inside an interrupt handler without first checking 
tli si the Schedulers busy flag at SE100FF is 0. 

The specified device cannot be found. ProDOS reports this error 
idler a GET_DEV_NUM command if it cannot locate the device. 

The device reference number is invalid, ProDOS reports this error 
if the device number is not in ils list of active devices. 
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Error 

Number Description 

$25 The ProDOS interna] interrupt vector table is full. ProDOS reports 

this error alter an ALLOCJNTERRUPT command if 16 interrupt 
vectors have already been allocated. 

$27 A disk I/O error occurred that prevented the proper transfer of data. 

If you get this error, the disk is probably irreparably damaged. You 
will also gei this error if there is no disk in a 5 Vi-insh disk drive, 
however. 

$28 The specified disk device is not present This error occurs if you try 

to access a second 5 '/i-ineh drive when only one drive is present, 
for example. 

$2B A write operation failed because the disk is write-protected. 

S2E An operation failed because a disk containing an open file was 

removed from the drive. ProDOS can return this error only for 
commands that involve checking the volume name. 

$2F The specified device is not connected to the system. This error 

occurs if there is no disk in a 3 Vn-inch drive, 

$40 The pathname syntax is invalid because one of the filenames or 

directory names does not follow the ProDOS naming rules or 
because a partial pathname was specified and a prefix is not active. 

$42 The file control block table is full. 

$43 The file reference number is invalid. 

| (4 The specified directory- was not found. This means that one of the 

subdirectory names in an otherwise valid pathname does not exist 

$45 'Hie specified volume director)' was not found. This error occurs 

when you remove a disk from a drive and then try to access it. 

$46 The specified file was not found. 

$47 The specified filename already exists. 

$48 The disk is full. 

$49 The volume directory is full. A volume directory cannot contain 

more than 51 entries. 

MA The format of the file specified is unknown or is not compatible with 

the version of ProDOS being used. 

Reference Section 379 



Error 
Number 


Description 


$4B 


The storage type code for the Ble is invalid. 


$4C 


An end-nf-file condition was encountered during a read operation. 


$4D 


The mark position is out of range. This error occurs if you attempt 
to position the mark pointer past the end of the file. 


$4E 


Access lo the file is not allowed. This error occurs when the action 
prohibited by the access code byte is requested. The access word 
controls read, write, rename, and destroy operations. The error also 
occurs if you try to destrov a directory file that is not empty. 


$.50 


The file is already open. You cannot reopen a file that is currently 

open. 


$51 


The director)' is damaged. ProDOS reports this error when the file 
count in a directory does not match the number of entries. 


$52 


The disk is not a ProDOS-formatted (or Apple III SOS-formatted) 
disk. ProDOS reports this error if it detects a non- ProDOS directory 
structure. 


$53 


A parameter is invalid because it is out of range. 


$54 


Out of memory error. This error is returned by the QUIT command 
if the ProDOS 8 application specified is too large to fit into the 
allowable ProDOS 8 memory space. 


$55 


The volume control block table is full. 


$57 


Two or more disks with the saint volume name are on one line. 
This is a "warning" error in that ProDOS still performs the operation 
on the first disk it deteets with the volume name required. 


$58 


The specified device is not a block device. ProDOS supports block- 
structured devices only, 


S59 


The level parameter (passed to SET_ LEVEL command) is out of 
range. 


S5A 


ill- volume bit map is damaged. ProDOS reports this error if the 
volume bit map indicates that the disk contains blocks beyond the 
maximum block count 
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Error 
Number 

$5B 



85C 



$5D 



S5E 



S5F 



$60 



Description 

Illegal pathname change. This error occurs if the pathnames 
specified in the CHANGE_PATH command refer to two different 
volumes. You can only move files between directories on the same 
volume. 

The specified file is not an executable system file. ProDO.S reports 
this error if you attempt to use QUIT to pass control to a file that is 
not a Pro DOS 16 system file (S16, code $B3.) (EXE, code $B5) or a 
ProDOS 8 system file (SYS, code $FR. 

The operating system specified is not available or not supported. 
ProDOS returns this error if you use FORMAT to format a disk with 
an operating system no! yet supported by ProDOS 16 or if you try 
to run a ProDOS 8 system program when the SYSTEM/PS file is not 
on the system disk. 

/RAM cannot be removed. This error when you QUIT a ProDOS 8 
application if the /RAM HAM disk that uses auxiliary memory (bank 
$01) cannot be removed. 

Quit Return Stack overflow ProDOS returns this error if you try to 
push another program ID on the Quit Return Stack (using the QUIT 
commamd) when the stack already has 16 entries on it. 

It is impossible to determine the last device which was accessed. 
This error can only be returned by the GET_LAST_DEV command. 



note: If a QVIT rammund results m tin error the enwr emir is nut returned to the application. Instead, 
the code appears in an iBteatartive dialog bin "" the screen. 



Table R10-3: The Major Functions in the Standard File Operations Tool Set ($17) 





Function 


Stack 


Description of 


Function Same 


Number 


Parameters 


Parameter 


SFGetFile 


$09 


WhereX (W) 


Top left-hand X coordinate 






WbereY (W ) 


Top left-hand Y coordinate 






Prompts tf 1 


Ptr to prompt string 






Filter Proe (L) 


Ptr to filter procedure 
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Function 


Stack 


Description of 


Function Name 


Number 


Parameters 


Parameter 






Type Li &t (L.i 


Ptr to typo list table 






Reply Record (L) 


Ptr to reply record 


SFPtitFile 


$0A 


WhereX(W] 


Top left-hand X coordinate 






WhereY (W] 


Top left-hand Y coordinate 






Prompts tr (L) 


Ptr to prompt string 






OrigNameStr (L) 


Ptr to default filename 






MaxLen (W) 


Maximum length of response 






ReplyRecord (L) 


Ptr to reply record 


SFShutdown 


S03 


| do parameters | 




SFStartup 


$02 


UserlD (W) 


ID tag for memory allocation 






DPAcldr (W) 


Address of 1 page in bank 1) 


Tabic R10-4: 


The Major Functions in the Scheduler Tool Set ($07) 




Fund 


Stack 


Description of 


Function Same 


Number 


Parameter* 


Parameter 


Seh Start up 


$02 


[no parameters] 




Sch Shut Down 


S03 


[no parameters] 




SchAddTask 


$09 


result :\V 


Boolean^ added to queue? 






Task Ptr (L) 


Ptr to interrupt handler 
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Listing 10-1: A Subroutine for Loading a ProPOS File into Memory 

LoadFile 



START 

Using FileData 

Using StartData 



Ask the user for the name of the fi-le to open: 



PushWord #120 

PushWord #40 
PushPtr SFPrompt 
PuahLong #Q 

PushLong * 

PushPtr ReplyRec 
SFGetFile 



IDA 
BNE 

SEC 
RTS 



good 
Loadtt 



; p r omp t 

; (no filter) 

;(no file type list) 
; reply record 



; Get the result 

•.Branch if it was "Dpen" 

■,Set carry if "Cancel" 



; Load the file into memory: 

Loadlt _DPEN QpenParms 

LDA refnum 

STA refnuml 

STA refnum2 

STA refnum3 

STA refnuml 



Open the file 

Get reference number 

and store it in 

other parameter tables 



_GET_EQF EOFParms 

PHA 
PHA 

PushLong EOF 
PushWord MylD 
PushWord **80QQ 
PushLong '0 
NewHand le 



;Get size of file 

-.space for result 

; Push a i2e of file 

'.Program ID 

; L o c k e d 

•, (means nothing here) 



Dereference the black handle so we can get a pointer for 
the READ command. The handle returned by NewHandle is still 
on the stack, so after PHD/TSC/TCD it's located at 
locations $03-$0G in direct page. 

PHD 
TSC 
TCD 
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LDA 


[*Q3J 


STA 


da ta_buf f 


LDV 


*2 


LDA 


[SQ3J,Y 


STA 


data_buff +2 



;Gel pointer (low) 
;Get pointer ( high ) 

PLD {Restore d.p. 

; Pop NewHandle result 



;Number of by teg to 
; read is set by EOF, 



;Disable newline feature 
; Read the entire file 
;Cloae the file 

;Carry clear means "Open" 





PLA 
PLA 






LDA 
STA 
LDA 

STA 


EOF 

r eques t 

EQF+2 

request *2 




_NEWLINE NLParms 
_READ ReadParms 
_CLDSE CloseParms 




CLC 

RTS 






END 




FileDate 


DATA 




• t SFGetFl 


le data: 




SFPrompt 


STR 


'Select a 


ReplyReo 

good 

f i letype 
auxtype 
F i 1 eName 
ful loath 


ANQP 

DS 

DS 

DS 

DS 

DS 


2 

2 

2 

16 

129 



;Non-zero if open pressed 
;ProD0S file type 
-,ProD05 auxiliary file type 
; Name of file in directory 0/ 
;Full pathname 



; Data for file I /"Q operations; 



OpenParms ANOP 

refnum DS 2 ^Reference number returned here 

DC M'FileName 1 ;Pointer to filename 

DS 4 ;Space for I/D buffer pointer 

EDFParms ANOP 

refnuml DS 2 

EDF DS 4 ;EQF returned here 
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NLParms 
ref num2 


ANQP 
DS 
DC 
DS 


2 

2 


ReadParms 
ref num3 
da ta_buf f 
request 


ANOP 

DS 

DS 

DS 

DS 


2 

-; 

4 


CI oseParnis 
ref nurn4 


ANQP 
DS 

END 


? 


Start Data 


DATA 




My ID 


DS 

END 


2 



^disable newline read mode 



Pointer to data area 
Number of bytes to read 
(number actually read) 



;Store MMStartup result here 



Listing 10-2: A Subroutine for Saving a Block of Memory to Disk as a 
ProDOS File 



This subroutine asks the user to enter a filename, 
then saves a block of data to that file on disk. 

On entry, da ta^buf f /da ta_buf f *2 points to the start 
of the data buffer. The length of the buffer is 
stored at actua 1 /actual +2 . These variables are 
defined in the FileData data segment. 



SaveFi le 



START 
Us ing 



Fi leData 
; Ask the user to enter a name for the file: 



PushWord 


#120 




PushWord 


#40 




PushPtr 


SaveProm 


Pt 


PushPtr 


FN_Defau 


It 


PushWord 


#15 




PushPtr 


ReplyRec 




.SFPutFi 


le 




LDA 


good 




BNE 


Savel t 




SEC 






RTS 







; prompt 

^default filename 
;15 characters max 
;reply record 



;Get the result 

;Branch if it was "Save" 

;Set carry if "Cancel" 



Reference Section 385 



Savelt ANOP 

;Set up a pointer to the area to be saved: 



LDA 


data_buf f 


STA 


w_bu f f er 


LDA 


data^buf f +2 


STA 


w_bu f f er + 2 



;Set up the number of bytes to be saved: 



LDA 


actual 




STA 


w_request 




LDA 


actual + 2 




STA 


w_r equest +2 




.CREATE 


Crea tePrms 


^Create the file 


_QPEN 


QpenParms 


; Open the file 



LDA refnum 

STA w_refnum 

STA c_refnum 

_NR1TE UriteParms ;Write data 

_CLD5E CloseParms 

CLC ;Clear carry if "Save" 

RTS 



END 

FileData DATA 
5 SFPutFUe data: 

; Non-zero if "Save" pressed 
; [ no t used ] 
; [not used) 
;Filename selected 
; Fu 1 1 pathname in 0/ 

SavePrompt STR 'Enter a name for the file:' 

FN_Default STR ' TEMPORARY . TXT ' ;Default filename 

; Data for file I/O operations: 

CreatePrms ANDP 

DC H'FlleName' ;Pointer to filename 

DC I2'*E3' ;access code 

DC 12*104' ;TXT file 



ReplyRec 


ANQP 




good 


DS 


2 




DS 


2 




DS 


2 


FileName 


DS 


16 


f ullpath 


DS 


129 
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DC 


14 


0» 




DC 


12 


1 » 




DC 


12 


i 




DC 


[2 


' 


OpenParms 


ANQP 






ref num 


DS 


2 






DC 


14 


F l leName 




DS 


4 




Wr 1 teParms 


ANDP 






w_refnum 


DS 


2 




w_buf f er 


DS 


4 




w_request 


D5 


4 




w_ac t ua 1 


DS 


i 





;aux type 
; storage type 
; creation date 
•.creation time 



^Reference number returned here 

-.Pointer to filename 

; Space for 1/0 buffer pointer 



Pointer to data ares 
Number of bytes to write 
(number actually written) 



Close-Parma ANOP 
c_refnum DS 2 

END 
Listing 10-3; The Structure of an SFGctFilr Filter Procedure 

* . • ■ i t i I i i i < i ■ i i i • i i < ( i . ■ m » < n i » » i . 

* This ia a filter procedure for SFGetFile. * 

* • 

* It mokes only TXT and SRC files selectable * 

* from a file list; all other file names are * 

* dimmed, « 

* • 

* Dn entry, here is what is on the stack: * 

* • 

* r esul t { word) ■ 

* pointer to directory entry (long) • 

* return address {3 bytes) * 

SF.Filter START 

; Direct page offsets: 



1 dDP 


EQU 


$01 


RetAddr 


EQU 


OldDP+2 


Di rEnt ry 


EQU 


RetAddr*3 


Result 


EQU 

PHD 
TSC 
TCD 


DirEntryM 




LDY 


#16 ; 




LDA 


IDirEntryJ ,Y 



Save direct page 
Align d.p* with stack 
Dffset to file type code 
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FPO 
FP1 



AND 


#*OOFF 


CMP 


#$B0 


BEQ 


FPO 


CMP 


#$04 


BEQ 


FPO 


LDA 


*\ 


BRA 


FP 1 


LDA 


#2 


STA 


Reau 1 1 


PLD 




LDA 


2,S 


STA 


6,S 


LDA 


1 ,5 


STA 


s,s 


TSC 




CLC 




ADC 


#4 


TCS 




RTL 





-, (use low byte only) 
•SRC file 1 ? 
;Yes, so branch 
■,TXT file? 

; Yes, so branch 

;1 ■ display/not selectable 



;2 ■ display/selectable 

;Save the result 

jReatore d-p. 

;Move 3-byte return 

; address up by 4 bytes. 



;Add 4 to the 
; stack pointer. 



END 
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CHAPTER 11 



Sound and 
Music 



One of the remarkable features of the Apple lies is its ability to create incredibly 
realistic sound effects and music. The cs can do this because its sound system is 
controlled by the powerful Ensoniq Digital Oscillator Chip (DOC), the same chip 
used in the profess tonal-quality Mirage Digital Sampling Keyboard and the Ensoniq 
Piano. 

With appropriate software, the Ensoniq DOC] can generate up to 32 user-defin- 
able sounds simultaneously. "Hie frequency of these sounds can be varied over a 
wide range and the volume can be set to any of 2.56 discrete levels. As a result, it 
is possible to mimic closely the acoustical behavior of any musical instrument. The 
DOC is also capable of sampling incoming audio signals, including voice samples. 
and converting them to digital form. 

Note: To maintain compatibility with earlier Apple II models, the GS also lets 
you create simple sounds by toggling the r.s speaker with a soft switch at $E0C030. 
You can use the SysBeep function in the Miscellaneous Tool Set to beep the spec.ker 
using this technique. SysBeep requires no parameters. 

This chapter takes a close look at the Ensoniq DOC and examines ways ol 
manipulating its internal registers to create sound and music. It also discusses using 
the Sound Manager to communicate with the DOC and to play back prerecorded 
sound patterns. Finally, the Note Synthesizer's ability to play musical times using 
different simulated instruments is covered. 



SOUND HARDWARE 

A block diagram of the c;s sound system is shown in figure 11-1. All sound-control 
commands are sent by a program running in the 65816 address space to the Sound 
General Logic Unit (GLU), The GLU passes them on to the sound circuitry con 
trolled by the Ensoniq DOC. Because the Ensoniq is isolated from the a58l6 by 



Figure 11-1. The Apple llc;s Sound System Block Diagram 



system volume control 



65816 



Sound 
GLU 



Ensomq DOC 
Sound Chip 



64K 

RAH 



s pea! er 




heedphane 
jack 



channel address 2 
eNinft*] alarm sifob» 
channel address 1 
channel address 
a.-.alsg output 
analog ground 
Analog wipui 



7-pin flolex 
connector 



Table 11-1: The Sound GLU Registers 



Register Name 


Address 


Sound Control 


SC03C 


Data 


5C03D 


Address Low 


SC03E 


Address High 


sc:o3i 



the GLU in this way, it can generate sound independently of the current application 
running in memory. That is. the application can perform other tasks while sound is 
playing in the background. 



Sound GLU 

The Sound GLU contains four registers for communicating with the DOC (see table 
11-1), The Sound Control register shown in figure 11-2 is the most complex. The 
lower four bits control the output volume level of the audio amplifier. The gs sound 
tools put the volume level (as set by the Control Panell into these bits before they 
access the DOC. 
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Figure 11-2. The Sound Control Kegister 



A 



IE0CO3C 

_ system volume 
(0 to 1 5) 



must be 

1 = auto-increment addresses 

= don't auto-increment 

1 = addresses are for DOC RAM 

" 1 = addresses are for DOC registers 

1 = DOC is busy 
" = DOC is free 



Bit 7 is a status bit that indicates whether the DOC is ready to respond to read and 
write operations, It is readv only if this bit is 0. 

Bit 6 controls whether the value in the Sound GLU 16-bit address register refers 
to an address in the DOC's special 64K BAM waveform buffer {bit = 1) or to a 
DOC register number (bit = 0). 

Bit 5 controls whether the GLU address register is to increment automatically 
after a data register access (bit = 1] or whether it is to stay the same (bit - 0). 
Setting the auto-increment bit makes it easier to access a range of registers or RAM 

addresses. 

The 16-bit address register contains either an address in the DOC RAM area or 
a DOC register number, depending on the state of bit 6 of the Sound Control 
register. For register accesses, the high-order part of the address register is ignored, 

The data register can be used to write data to DOC registers or to DOC RAM, 
as well as lor reading data. Here is how to read or write a byte of data: 



1. Adjust the value in the Sound Register to indicate whether a DOC] register 
or DOC RAM is to be accessed, and set the auto-increment bit to the desired 
state. The volume bits should be set to the system-volume value (it is stored 
in the low-order four bits of $E100CA). 
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2, Store the DOC register number, or the DOC RAM address, as the ease may 
be, in the address registers. 

3. Store the data byte in the data register (write operation) or load the data 
byte from the data register (read operation I 

One caveat should be mentioned that affects read operations involving the DOC 
registers or DOC RAM. A read operation immediately following the storing of an 
address in the Sound GLL 1 address register lags by one cycle, so you must always 
ignore the first result returned. H auto-increment is on, you need only ignore the 
first result in a sequence of successive read operations. 

A final note on the Sound CLA DOC registers: Apple has warned developers 
not to access these registers directly, because their Junctions or addresses may 
change in future versions of the GS. If you need to manipulate the DOC registers 
or DOC RAM, you should use the Sound Manager functions described later in this 
chapter. 

Ensoniq DOC 

The Ensoniq DOC" is the heart of the c;s sound system. It contains 32 independent 
oscillators (numbered from to 31) that can be used to sample, at user-definable 
rates, digitized audio waveforms stored in memory. This sampling rate indirectly 
sets the frequency of the sound generated by the oscillator. The DOC has a total of 
227 internal registers for controlling the operation of its oscillators and of the DOC 
chip itself. 

Because each oscillator operates independently of any other, you can play 32 
waveforms simultaneously! The gs sound tools pair these oscillators oil' to create 16 
voices or generators. This is done to make it possible to create richer and more 
realistic sounds. One of these generators (corresponding to oscillators 30 and 31) is 
reserved tor use as a general-purpose timer by the C.S sound tools. 

The output signal of the DOC goes to an analog circuit thai amplifies the signal 
before sending it to the GS speaker (or other audio output device), The gain of the 
amplifier is the system volume set by the Sound Control register in the Sound 
GLU. 

The audio wuvelorms are stored in a fi4K RAM memory area dedicated to the 
DOC. Ibis RAM does not form part oi the 65Sl.fi address Space and can be accessed 
only through the Sound CLU registers. 

An audit) signal is called a ivaicfttrm, because it you plot a graph of signal intensity 
(amplitude) versus time for a pure tone, you get a series of sinusoidal wave's, as 
shown in figure 11-3. The frequency (or pitch) of the signal is expressed in cycles 
per second, or Hertz. As far as the DOC is concerned, however, the waveform need 
not be a symmetric wave at all. It could have a completely random form (white 
noise) or a complex, bul periodic, form made up of a combination of sinusoidal 
waves. By playing with the waveform you can generate all sorts of interesting sound 
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Figure 11—3. Audio Waveforms 



Amplitude 




one cycle 



Time 



variations; in fact, one of the reasons different musical instruments do not sound 

exactly the same is that the waveforms they generate I amr pitch are different. 

A digitized waveform stored in the DOC RAM area is a series of bytes repre- 
senting the amplitude of the sound wave at fixed time intervals. The bytes can take 
on values from $01 (low volume) to $FF (high volume). A DOC oscillator stops 
when it encounters a $00 byte. 

Sound Output 

The DOC- steps through a waveform at a user-definable rate and feeds the bytes it 
reads to a built-in digital-to-analog converter The analog output from the converter 
goes to four different destinations: 

• The built-in two-inch speaker 

• The RCA mini headphone/speaker output jack. You can connect Walkman- 
style headphones or (with an adapter) the input line of your stereo set to this 

jack 

• Pin 3 of the 7-pin Molex connector used by the DOC 

■ Pin 11 of the KGB video connector (this is for the benefit of RGB monitors 
with in tenia] speakers) 

Note that il the headphone/speaker jack is in use, output to the speaker is auto- 
matically disabled. 

Software that creates sound using the DOC can assign the sound to any of eight 
output channels. (The DOC actually can handle up to sixteen channels, but the GS 
supports only eight of them.) The channel address appears on pins 4, 5, and 7 of 
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Table 11-2: The 227 Ensoniq DOC Roisters 



Register Nome 



Register 
Number 



Frequency Low 
Frequency High 
Volume 

Data 

Address 
Control 
\\ ;n ejbrm 

Oscillator Interrupt 
Oscillator Enable 
Analog-to-Digital Converter 



$00 + OSC 
$20 + OSC 

$40 + OSC 
$60 + OSC 

$80 + OSC 
$A0 + osc 
$C0 ^ OSC 

$E0 
SE1 

SK2 



OSC = the oscillator number ($00 to »1F>. These are 8-bit registers. 



the Mole* coWtor. An external demultiplexer can monitor this address and direct 
the output signal (on pin 3) to a different speaker For each channel. The MDldeas 
SuperSonie stereo card, for example, works with two speakers sending all sound 
for even-numbered channels to one of them and all sound for odd-numbered chan- 
nels to the other. 

THE ENSON1Q DOC REGISTERS 

Each of the 32 oscillator, in the EnsouU, DOC has seven 8-bit registers associated 
with it (see table J l-2i. Two of these registers set the waveform sampling rate 
(frequency) of the oscillator, the others set the volume, the position of the useiUator i 
waveform in the DOC RAM area, the characteristics of the waveform, and the 
oscillators operational mode. Finally, one roister contains the last byte the oscillator 
loaded from the waveform table. . . 

There- .re also three general-purpose DOC registers you can use to enable 
oscillators, read interrupt status information, and perform analog-to-digttal conver- 
sion of incoming audio signals. . 

In total there are 227 registers inside the Ensoniq DOC chip. The sections that 
follow examine precisely how to use tin i 
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Oscillator Registers 

This section discusses the seven registers assigned to each oscillator. Keep in mind 

thai, as shown in tabic- 11-2. the register number tor a particular oscillator is the 

sum of a base register number and the oscillator number. For example, the base 

ter number lor Volume is $40; therefore, the Volume register for oscillator SIC 

5C ($40 • SIC). 

Frequency Low i$0O-$lF) and Frequency High ($20-$3F). The DOC's int. 
16-bit frequency register is a concatenation of the Frequency Low and Frequency 
High registers. The value stored in this combined register sets the speed at winch 
the oscillator retrieves data from the waveform In memory. This speed, called the 
Sampling rate, is given by the following formula: 

[Scan Kate) * F , , , 

Sampling rate = J — g St+BESi " samples/second 

where 

7 159* 10* , , 

Scan Rate - (g ^ (osc+2)) /second 

In these formulas, F represents the value stored in the 16-bit frequency register 
and OSC represents the number of enabled oscillators. RES is the number stored 
in the resolution bits of the Waveform register (see below). 

Note that the sampling rate is not the same as the frequency oi the output signal 
to the speaker. This frequency depends on the size of the waveform being played 
by the oscillator. To determine the frequency of the speaker signal, divide the 
sampling rate by the number of bytes needed to define one cycle oi the waveform. 

Volume ($40-$5F). The Volume register sets the volume of the oscillator. When 
the DOC reads a waveform data byte from memory, it multiplies it by the value in 
the Volume register before passing it to the output amplifier. 

Data (S60-S7F). The Data register contains the last byte the DOC read from the 
waveform for the oscillator. 

Address ($80~$9F)- The Address register contains the page number inside the 
DOC; RAM at which the waveform for the oscillator begins. The waveiorm must 
start on a page boundary, 

Control ($A0-$BF), The Control register is used to set the operational mod. oi 
the oscillator. It controls the output channel with which the oscillator works, whether 
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Figure 11-4. The Oscillator Control Register 



always 
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DOC Registers $AO-$BF 

1 = halted 
= running 



oscillator mode 
Free-Run 

I One-Shot 

1 Sync 

1 I Swap 

1 = interrupt on 
= Interrupt off 

channel address 
(0 to 7) 



interrupts are enabled, the oscillator mode, and whether the oscillator has been 
halted or is playing. 

The meanings of each of the bits in the Control register is shown in figure 11-4. 
The channel address is three bits wide SO there are eight possible output channels. 
As shown iti figure 11-1, the channel address lines are brought out at the 7-pin 
Molex connector. By connecting a multiplexer to this connector, you can easilj 
generate multiphonic sound. 

If interrupts are enabled for the oscillator, the interrupt flag in the Oscillator 
Interrupt register is set when the oscillator finishes playing its waveform. In addition, 
the oscillator number is stored in bits 1-5 of the Oscillator Interrupt register 

The halt bit controls whether the oscillator is playing. When it is 1, the oscillator 
is halted and no sound is generated. When it is 0, the oscillator begins playing its 
waveform. 

Four different oscillator modes can be used: 



Free-run mode (0). In free-run mode, the oscillator plays the waveform again 
and again until the halt bit of the Oscillator Control register is set by the 
application. (The oscillator also halts if it encounters a $00 byte in the waveform 
table.) 
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Figure 11—5. The Waveform Register 
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DOC Registers $CO-$DF 



waveform resolution 
(0-7) 



waveform table size 

256 

1 512 

1 1024 

1 1 2046 

1 4096 
10 1 8192 
1 1 16384 
1 I 1 32768 



One-shot mode (1). In one-shot made, the oscillator plays tin waveform once 
and then sets its halt bit and stops. This is the mode yon would use if the 
waveform represents a long, non-periodic sound. 

Sync mode (2). In sync mode, a pair of adjacent even/odd oscillators work 
together in synchronization. (The odd-numbered oscillator always has the 
higher number of the two.) In particular, when the even-numbered oscillator 
begins playing its waveform, the odd-numbered one begins playing its waveform 
as well. 

Swap mode (3). In swap mode, as in sync mode, a pair of adjacent even 'odd 
oscillators work together, but in a different way. First the enabled oscillator 
runs in one-shot mode. When it finishes stepping through its waveform table, 
it sets its halt hit and then clears the halt hi I of the other oscillator so that it 
will begin playing its waveform. An even/odd pair of oscillators in swap mode 
is called a generator. 

Waveform ($C0-$DF). The Waveform register contains the size of the waveform 

being played by the oscillator. It also tells the DOC the resolution of the waveform. 

As shown in figure 11-5, the size of the waveform is called the Table Size and is 

represented by "a 3-bit code number. These codes correspond to sizes ol 256, 512, 
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Figure 11—6. The Oscillator Interrupt Register 
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DOC Register $E0 

— always 1 



oscillator number that 
caused the interrupt (0-31) 

always 1 

1 = interrupt occurred 

= interrupt did not occur 



1024, 2048, 4096, 8192, 16381. and 32768 bytes, respectively. No other sizes are 
permitted. 

The waveform resolution is also represented b\ a 3-bit code number from to 
7. Earlier in this section the ways in which this value participates in the waveform 
sampling rate calculation were discussed. If the resolution is raised by 1. the 
sampling frequency is halved; similarly, if it is lowered by one. the sampling fre- 
quency doubles. In most cases, the resolution code should be set equal ti» the Table 
Size code so that the effective frequency of the signal sent to the speaker is not 
affected b\ powers of two. 

General Registers 

The following three registers in the UOC are of general use and do not relate to 
any specific oscillator. 

Oscillator Interrupt ($E0). The Oscillator Interrupt register indicates whether an 
interrupt has occurred and. if so, which oscillator caused it (see figure 11-6), An 
interrupt will occur when an oscillator finishes playing its waveform if the interrupt 
enable bit in the oscillator's Control register is set to I. Bit 7 contains the interrupt 

Hag. and hits 1-5 contain the number of the oscillator that caused the interrupt (0 

l,, \) 

Oscillator Enahh ($E1). This register controls the number of enabled oscillators 
(see figure I L-7). Tins number can range from 1 to 32 and is stored in bits 1-5 of 
the register. iThe minimum is not because at least one oscillator must he enabled. ! 
Oscillators arc enabled in numeric order, starting with #0. 
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Figure 11-7, The Oscillator Enable Register 
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DOC Register $E1 
— always 



number of oscillators 
enabled (1 to 32) 

always 



Note that the number of enabled oscillators affects the rale at which the DOC 

the oscillator wavetables. The more oscillators arc enabled, the slower the rale. To 

simplify calculations, the CS sound tools enable all 32 oscillators. 

Analog-io-Digital Converter ($E2). This register contains the output of an analog- 
to-digital converter whose input line is connected to pin 1 of tin Mo lex connector 
used by the Ensnniq chip (see figure 1 1—1). 

To read the result of the analog-to-digital conversion and to initiate the next 
conversion, all you have to do is read this register. The conversion process takes 
about 31 microseconds, so do not read the register again until this time has elapsed. 
If you do, the result read will be meaningless 

SOUND MANAGER 

The Sound Manager (tool set 8) lets you manipulate the DOC registers and DOC 
RAM In such a way that you do not have to concern yourself with the mechanics ol 
the Sound GLl' or the I/O addresses it uses, It also defines and lets you use a free- 
form synthesizer which is useful for playing back digitized sound effects or one long 
musical piece. 

The Sound Manager deals with oscillators in swap mode pairs called generators. 
Sixteen generators are defined, but one is reserved for use as a timer, 

Before using the Sound Manager, start it up by calling SouudStartup: 



PushWord DPAddr 
_SoundStar t up 



-,Pointer to one-page in bank $00 



The direct page work area whose address is passed to SouudStartup must be i 
aligned. 

When you are through with the Sound Manager, call SoundShutDown (no pa- 
rameters). It shuts off all the DOC oscillators 
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Accessing the DOC RAM Area 

Before you cm < rente sound with the DOC, there must be a waveform in the DOC 
RAM. You can put one there with WriteRamBlock: 



PuahPtr MyWave 
Pu5hWord #*0000 
PushWord #1100 
.WriteRamBlock 
RTS 



-.Pointer to wave data 
•Starting address in DOC RAM 
■>Size of wave in bytes 



MyWave DS 



2S6 



; Insert wove definition here. 



The low-order byte of the starting address passed to WriteRamBlock should be $00, 
because the DOC expects waves to begin on page boundaries. The wave size should 
be $100, $200. $400, SHOO, $1000. $2000, $4000, or $8000, because these are the 
i k sizes the DOC supports. 

The waveform can contain any series of one-byte values, but it must not contain 
a $00 byte, because a DOC] oscillator stops playing when it encounters a value. 
The mid-range value of $80 corresponds to a output voltage. Listing 11-1 shows 
how to create two types of simple one-page waveforms, a sinusoidal wave and a 
triangular-shaped wave. 

To read data from DOC RAM to main memory, use ReadRamBlock: 



PushPtr MyBuffer 

PushWord #*1 000 
PushWord #*400 
_ReadRamBlock 



;Pointer to buffer in main memory 
^Starting address in DQC RAM 
^Number of bytes to transfer 



Volume Control 

The Sound Manager has two functions related to volume settings: GetSound Volume 
and SetSoundVolumc. They can be used to read or set the volume level of any 
generator or the system volume. 

To read the volume, call GetSoundVoIuiiie as follows: 



PHA 

PushWord GenNum 

_Ge t Sound Vo 1 urne 

PLA 



; space for result 
generator number 

;Pop the volume setting 



If GenNum is between and 14, it represents a generator number, and the volume 
number lor that generator is returned on the stack. The volume number can range 
from to 255. 

If GenNum is greater than 14, the system volume is returned. The system volume 
ranges from to 15 only and is returned in hits 4-7 of the result. 
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You can set the- volume of a particular generator, or the system volume, with 
SetSound Volume: 



PushWord VolLevei 
PushWord GenNum 
SetSoundVo lume 



; Volume level (0 to 15] 
; Generator number 



As with GetSoundVoluine. if the generator number is above 14, the system volume 
is affected and the volume code must be stored in bits 4-7 of Vol Level. 



Free-form Synthesizer 

The Sound Manager supports a free-form synthesizer you can use to play back any 
digitized sound stored in the DOC RAM area It is intended for the playback of 
complex, non-repeatable waveforms that have previously been digitized. To play 
musical notes, it is much more convenient to use the Note Synthesizer, as we will 
see below 

The main free-form synthesizer function is FFStartSound. It allocates a particular 
generator and causes it to start playing a waveform stored in memory. Here is how 
to call it; 



PushWord #GenNum*256-$Q1 
PuahPtr FF_Parm5 
_Ff"5tar tSound 
RTS 



■.Generator (high), mode (law} 
jpointer to parameter block 



FF^Parma ANOP 




DC 


! 4 • WaveFornt' 


DC 


12'WaveSize 1 


DC 


12 'Frequency' 


DC 


I2'DQC_Addr • 


DC 


12'BufferSize 1 


DC 


M'NextWave' 


DC 


I 2 'Volume' 



Pointer to waveform 

Size of waveform in pages 

Playback rate 

DDC position for wave 

DOC wave size code 

Pointer to next parm table 

Generator volume (0-255) 



The first parameter passed to FFStartSound contains the generator number (0 to 
14) in the high-order byte and a mode code of $01 in the low-order byte. The value 
^01 means the generator is used for free-form synthesizer mode. 

The parameter table tells the tree-form synthesizer all it needs to know about 
the waveform to be played. WaveForm is the address of the waveform in the 65816 
memory space and Wave Size is its size in 256-byte pages. 

The Frequency field contains the number to be placed in the DOC's frequency 
register for the two oscillators in the generator; this value can be determined using 
the following formula; 
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32 * Samplin g Rate 
ueney Register = ._„ 

The sampling rate is expressed in cycles/second (Hertz) in this formula, 

DOC_Addr is the starting address in the DOC RAM area to which the waveform 
is to be transferred before il is played, BufferSize is a code from to 7 representing 
the Table Size of the form. (See the discussion of Table Size in connection with the 
DOC' Waveform registers earlier in this chapter.) 

NextWave is the address of the parameter block for the waveform to be played 
when the current waveform has been finished. Set it to for the last parameter 
block. If you want to play one wave > r and over again, set the NextWave parameter 
to the address of the one and only parameter table, (You can stop the sound with 
FFS top Sound.) 

Volume is the volume of the waveform and can range from (low) to 255 (high). 

Four other major functions can be used to control the free-form synthesizer or 
to check its status: 

• FFStopSound stops one or more generators 

• FF Sound Status checks the status of all generators 

• FFOeneratorStatus cheeks the status of one generator 

• FFSoimdDoncStatus determines it the synthesizer is playing a waveform 

Two minor functions, SetSoundMlKQV and SetUserSonodlRQV, are used to install 
special sound interrupt handlers and are rarely used by applications. They are not 
discussed here. 

You can use FFStopSound to stop any generators that may still be running: 

Pushklord GenMask ^Generator mask 

_FFSt opSound 

Math generator corresponds to a unique bit in the generator mask: bit for generator 
#0. bit 1 for generator #L and so on. To slop a particular generator, set its bit in 
the mask to 1. For example, to slop all IS usable generators, use a mask of $7FFK 
Bit 15 of the mask corresponds to the reserved generator, so it must always be (I in 
the mask. 

To determine which generators are playing at any given time and which are idle, 

use FFSoundStatus: 

PHA ;Space for result 

_FFSound5tatu5 

PLA 'Pop th e generator mask 
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FFSoundStatus returns a generator mask that is of the same form as the one pa 

to FFStopSuund. If a bit is set to 1 . the generator corresponding to that hit is 

currently playing. 

FFCeneratorStatus returns the first two bytes of the generator control block 
(GCB) for the generator. These bytes contain the synthesizer mode, generator 
number, and channel number. 

Hie CCB is a 16-byte data structure used by the free-form synthesizer to keep 
track of the attributes and status of the generator. The GCB's for each of the sixteen 
generators are stored in tin- one page direct page area whose address is passed to 
SoundStartup. 

To call FFGeneratorStatus, pass it the number of the generator in question: 

PHA ;space for result 

PushWord GenNumber -.Generator number 
_FFGeneratorStatus 

pj_A ",Pop the status word 

Bits 0-3 of the status word contain the generator number, tuts 4-7 contain the 
output channel number {normally 0) and bits S-ll contain the mode code. The 
mode code is SI for the free-form synthesizer. Bit 15 is set to 1 if the last block of 
the waveform has been loaded. 

The last major free-form function is I lSuundDuneStatus Call it to determine il 
a free-form synthesizer generator is currently playing anything: 

PHA ; 5 pace for result 

PushWord GenNumber '.generator number 

_FF5oundDone5tatus 

PLft ;8usy code 

If the result is $0000, the generator is still playing; if it is SFFFF, it is done. 

Low-level Access to DOC Registers and DOC RAM 

As mentioned earlier in this chapter, yon should not use the Sound CLU registers 
to communicate directly with the Ensoniq DOC registers or RAM. Instead, you 
should use the Sound Manager's GetTableAddress function to get the address ol a 
table containing the addresses of six low-level DOC control subroutines; you should 
then call these subroutines to communicate with the DOC. GetTableAddress also 
returns the addresses of two useful oscillator/generator translation tables and a table 
of GCB offset addresses. 

Here is how to call GetTableAddress: 

PHA iSpace for result 

PHA 

_GetTableAddres5 

PopLong DQC.Table ; Pop pointer to table 
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Table 11-3: The Low-level DOC Subroutine Table Whose Address Is Returned 
by GetTableAddress 



Subroutine 

or 

Table Pointer Offset 



Read Register 

Write Register so I 

Read RAM SOS 

Write RAM $<M 

Read Next 
Write Nexl 
Oscillator Table 
Generator Table SIC 

CCB Table 



DOC_Table should be a direct page variable, so that you tan use it to indirectly 
access the contents of the table. 

The format of the table whose address is returned by GetTableAddress is shown 
in table 11-3. It contains nine 4-byte addresses (low-order bytes first) of low-level 
DOG subroutines or data tables. 

The first six entries in the table are 4-byte addresses of subroutines (low-order 
bytes first) that can be called with a JSL instruction. Unfortunately, the 65816*5 
indirect long addressing mode is useful only if you know in advance where the 
address table is located, and you do not have this information. The easiest way to 
call a subroutine is to store its address in the 3-byte operand of a JSL instruction, 
low-order byte Hrst. This involves ugly self-modifying code, but there is no easy 
alternative. 

For example, here is how to set up a JSL to the write subroutine (at offset $04): 



TablePtr GEOU $00 ;pointer to low-level table 

p HA '.space for result 

PHA 

_GetTableAddre5s ;Get table pointer 

PopLong TablePtr 
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IDA [TablePtrl ;Get address (low) 
CLC 

ADC #$04 • . . . add offset 

5TA J5L_Patchi-1 ;5et low word of operand 

LDY #2 

LDA [TablePtrl, Y jGet address (high) 

ADC #0 ; (adjust for any carry) 

SEP #$20 ;8-bit accumulator 

LONGA DFF 

STA JSL_Patch+3 ;Save bank byte 

REP #$20 ?16-bit accumulator 

LONGA ON 

RTS 

JSL_Patch JSL $123456 ;Call low-level subroutine 

RTS 

Before a DOC subroutine is called, the 65816 must be in native mode with 16-bit 
index registers <x=0) and an 8-bit accumulator l'm = l}. If you are in full native mode. 
you can switch to an 8-bit accumulator with the following assembler instructions; 

SEP #$20 
LQNGA QFF 

you call the subroutine, sou can switch back to a 16-bit accumulator with a 
REP #$20 instruction, followed by a LONGA ON directive. 

The Oscillator Table entry is a pointer to a 16-byte generator-to-oscillator trans- 
lation table. This table contains a list of one-byte oscillator numbers, in generator- 
number order. The second oscillator for a given generator is always the next higher- 
numbered one. For example, to determine the two oscillators for generator #9, you 
would use a code fragment like this: 

OacTbl GEQU $04 



;Get pointer (low) 
;Get pointer (high) 

(Switch to 8-bit accumulator 
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LDV 


#$18 


LDA 


[TablePtrl ,Y 


STA 


OsoTbl 


LDY 


#$1A 


LDA 


[TablePtrl ,Y 


STA 


QscTbl+2 


SEP 


#$20 


LDNGA 


DFF 



LDV 


#9 


LDA 


[OscTbl] ,V 


STA 


05Cl 


INC 


A 


STA 


0sc2 


REP 


#$20 


LDNGA 


DN 


RTS 





;Generator #9 

;Get first oscillator 

; Save number 

; Second oscillator = first - 1 

j Save number 

-.Back to 16-bit accumulator 



The Generator Table entry points to a 32-byte table you can use to determine which 
oscillators are associated with which generators. It contains a list of generators in 
oscillator-number ordci 

The CCB Table contains the one-byte offset positions to the generator control 
blocks for the 15 usable generators, in generator-number order. The base point for 
the offsets is the address of the bank $00 page passed to SoundStartup. Most 
applications have no need to access the CCB. 

The methods that can be used to call the six low-level DOC subroutines are 
discussed in the sections below, 

Bead Register. Call this subroutine to read the contents of any of the 227 registers 
in the DOC. The register number must be in the X register. The contents of the 
specified DOC register is returned in the 8-bit accumulator 

Write Register. This subroutine stores a number in any DOC register. The register 
number must be in the X register, and the 8-bit accumulator contains the number 
to be written. 

Read RAM. This subroutine reads the value stored at any location in the DOC 
RAM area. On entry, the X register must contain the address. The value is returned 
in the 8-bit accumulator. 

Write RAM. This subroutine writes the value in the 8-bit accumulator to any 
location in the DOC RAM area. On entry, the address to be written to must be in 
the X register. 

Read Next. If the previous low level call was Head Register or Write Register, 
this subroutine returns in the 8-bit accumulator the data in the next DOC register. 
11 the previous call was Read RAM or Write RAM, it returns the data in the next 
RAM location. 

Write Next. This subroutine is similar to Read Next, but it returns in the 8-hit 
accumulator the contents of the next register or the next RAM location, as ihe case 
may be. 
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Using Low-level Subroutines: Digitizing Analog Input 

The CONVERTER program in listing 11-2 illustrates how to call low-level DOC 
subroutines. It digitizes an incoming analog signal (which appears on pin 1 of the 
Ensoniq's Molex connector) by reading DOC register $E2 again and again until a 
32K buffer fills up or until ESC is pressed. (To play the sound back, you would 
transfer the sample to DOC] RAM and call FFStartSound.) 

You can use a device such as the MDldeas SuperSonie stereo card (with Digitizer 
option) as the source of the analog signal to be digitized. The SuperSonie receives 
its signal through an RCA phono connector, which you can connect to the output 
line of a radio, tape recorder, record player, CD player, television, or a musical 
instrument. 

The CONVERTER program uses a sampling rate of approximately 1G00 samples/ 
second, but it can be changed by adjusting the counter in a delay loop in the 
DoSample subroutine. According to the Nyquist Sampling Theorem, the sampling 
rate should be at least twice the frequency of the highest-frequency component of 
the sound being recorded If it is not, the sound will appear distorted when you 
play it back. 

The CONVERTER program uses the JSL patch technique for setting up the call 
to the DOC read subroutine. When the subroutine is called, the DOC register 
number is in X and m = l, as required. 



NOTE SYNTHESIZER 

The free-form synthesizer used by the Sound Manager is most useful for playing 
back long sound patterns that have been previously digitized. It is not particularly 
useful for playing musical notes or synthesizing the effect of musical instruments. 

It is the Note Synthesizer (tool set 25) that you will use most often to create 
musical melodies on the GS. It is capable of playing all standard musical notes using 
the characteristics of any instrument you care to define. With a minimum of extra 
effort, you can use the Note Synthesizer to assist the application in playing back 
sequences of notes in a song. 

The general procedure for using the Note Synthesizer to play a pure note is quite 
simple: 



1. Load a waveform into DOC RAM (with Write RarnBlock) 

2. Get a generator (with AllocGen) 

3. Play the note (with NoteOn) 

4. End the note (with NotcOff ) 
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Difficulties arise when defining the characteristics of the instrument to be used to 
play tin not. This requires an understanding of terms such as ADSR envelope, 
vibrato, pitchbend, and semitone. The process of defining an instrument will be 
discussed later in this chapter. 

Starting up the Note Synthesizer 

'Die start-up function for the Note Synthesizer is NSStartup. Before calling it, you 
must call Sound Startup to start up the Sound Manager. This is net ess try because 
the Note Synthesizer uses Sound Manager functions to perforin some of its chores. 
Here is how to call NSStartup: 

PushWord UpdateRate ^Envelope update/interrupt rate 

PuahPtr MySequencer jPointer to interrupt handler 

.NSStartup 

The UpdateRate variable defines an interrupt rate for the notes played by the Note 
Synthesizer, This is the rate at which the ADSR (attack, decay, sustain, release) 
envelope tor the instrument selected to play the note is generated, {ADSR envelopes 
and instruments are described below.:' The UpdateRate variable rs in units of 0.4 
Hz and should normally range from 75 (30 Hz) to 500 (200 Hz). The higher the rate, 
the better tin- note will .sound, hut the main application will he interrupted more 
oiten and will appear tn slow down while music is playing. 

When a Note Synthesizer update interrupt occurs, the system interrupt handler 
calls the user-defined My Sequencer subroutine. This subroutine can keep track of 
the number of times it has been called and turn notes on and off at the appropriate 
times. For example, if the update rate is 30 Hz and a note is to play for one-half 
second, MySequencer would wait for 15 interrupts before turning the note off (and, 
in most cases, turning on the next note in the song). 

Playing a Note 

To play a note with the Note Synthesizer, you must start by using AllocGen to get 
a generator with which you can work; 

PHfl ;space for result 

PushWord GenPriority ; generator priority 
_fll loc&en 

PLA ;Pop generator number 

The GenPriority parameter passed to AllocGen is a number from 1 to 128 and 
represents a priority code for the generator. For most purposes, you can assign a 
priority of 127 to all allocated generators. 

The priority indicates the degree to which the generator will he "stolen" by 
subsequent calls to AllocGen If all generators are in use. (Generators to 13 may 
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Figure 11—8. Waveforms for Different Musical Instruments 
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be allocated; the Sound Manager and Note Synthesizer reserve one generator each.) 
AlloeGen first tries to allocate a generator that is not in use (priority = 0). If it 
cannot find one, it steals one with the lowest priority that is less than or equal to 
GenPriority (A generator with a priority of 128 cannol be stolen, however ) AlloeGen 
returns an error if no generator qualifies. 

If AlloeGen dors allocate a generator, it assigns-it a priority of GenPriority. 

Once you have allocated a generator, you must load a waveform for the generator 
into memory. For simplicity, you can just load a simple sinusoidal wave or a triangle- 
shaped approximation. Keep in mind, however, that real musical instruments have 
different waveforms, so you should use them for more realistic sound. The waveforms 
for some common instruments are shown in figure 11-8, 

To play the note, call NoteOn: 



PushWord GenNum 

PushWord Semitone 

PushWord Volume 

PushPtr My Instrument 
_NoU ^n 



;generator number 

;MIDI semitone (frequency) 

1 Volume 

j Pointer to instrument definition 



MIDI stands for Musical Instrument Digital Interface, an international standard for 
digital musical devices. MIDI semitone codes range from to 127, where middle 
C is 60. Semitone codes for other notes can lie deduced from the information in 
table 11-4. 

The Volume parameter also ranges from to 127 and is roughly equivalent to 
MIDI velocity (the speed at which a note is struck). Each group of 16 units of the 
volume parameter corresponds to a 6-decibel change in volume. 

The M\ Instrument parameter is by far the most complex parameter. It points to 
a parameter block that describes, in meticulous detail, changes to be made to ihe 
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Table 11-4: 


MIDI Semitone Codes 


Jsed by the Note 


Synthesizer 


Octave 


Semitone 
Code 


Pitch 


Offset 

within Octave* 


1 


36 


C 


+ 


2 


48 


c# 


+ 1 


3 


60 


D 


+2 


1 


72 


D# 


+ 3 


5 


84 


E 


+ 4 






F 


+ 5 






F# 


+6 






G 


+ 7 






G# 


+8 






A 


+9 






A# 


+ 10 






B 


+ 11 



*Add these codes to the semitone base code for the OOtSVC being used. 



basic waveform when playing the note. By adjusting the instrument parameters, 
you can simulate the characteristics of any musical instrument. 

The general form of an instrument definition is shown in table 11-5. An actual 
example is shown in listing 11-3. It begins Willi the definition of an AUSR envelope 
for the instrument. As shown in figure 1 1-9, ADSK stands for attack, deeay. sustain, 
and release, the four consecutive phases a waveform passes through when it is 
played, The amplitude of the ADSR envelope at any given time represents the 
maximum amplitude (volume) of the underlying waveform for the note; the waveform 
is still oscillating at the proper frequency, hut its maximum amplitude is being 
modulated. 

To explain the meaning of attack, decay, sustain, and release, it is best to consider 
one particular instrument, say a piano. The slope of the attack stage is proportional 
to how hard you strike the piano key; the harder you strike it, the faster the volume 
reaches its maximum. Demy refers to the degradation in volume after the attack 
maximum has been reached. Sustain refers to how the volume changes as yon hold 
the key down. For a piano, the sound is sustained for some tune, but gradually 
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Table 11-5: The Instrument Definition Data Structure 



Field Name 



ADS R_ Envelope 

Release Segment 

Priority Increment 

Pitch BendRange 

VibratoDepth 

VibratoSpeed 

Spare 

AWaveCount 

BWaveCount 

AWaveList 

fi Wave List 



Offset 



soo 

SIS 
$19 
S1A 
SIB 

SIC 
$1D 
$1E 
$1F 

sin 

S20 + 6 * AWaveCount 



Figure 11-9. The ADSR Envelope for a Sound 



attack decay sustain 



release 



amplitude 




time 



fades away; for other types of instruments, such as an organ, there is little change 
in volume during the sustain stage. The final stage is the release stage, which 
corresponds to the complete release of the key. For most instruments, tbe volume 
drops off rapidly during the release stage. 

The meaning of each parameter in an instrument definition is discussed below. 
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ADSR_Envelope. The ADSR_Envclope field is made up of eight 3-byte entries 
that define the shape of the ADSR envelope at eight different stages: 

• Stage 1: volume 1 (byte), ineremenl 1 (word) 

• Stage 2: volume 2 (byte*, increment 2 (word) 

• Stage 3: volume 3 (byte), increment 3 (wqkI) 

• Stage 4: volume 4 (byte), increment 4 (word 

• Stage 5: volume 5 (byte), increment 5 (word) 

• Stage 6: volume 6 (byte), increment 6 (word) 

• Stage 7: volume 7 (byte), increment 7 (word: 

• Stage H: volume 8 (byte), increment 8 (word) 

Tn each threesome, the first byte is a volume (0 to 127) and the following word is 
an increment. For a given stage, the increment value indicates how Fast the volume 
is to change from what it was in the previous stage to what it is in the current stage. 
That is. the increment sets the slope of the ADSK envelope for a particular time 
interval. 

The time needed to slope up (or down) to the volume of a particular stage can 
be calculated from the following formula: 

time = absilast volu me - new volume) * 256 
increment * update rate 

where abs means absolute value and the update rate is the one passed to NSStartup. 

Releases e foment. The ReleaseSeginent field of the instrument definition contains 
the number (minus one) of the ADSR_Envelope stage to which the Note Synthesizer 
goes when the note is released (a note is released when you call NoteOff). In most 
cases, the instrument will release to a zero volume in one stage, so the volume byte 
for this stage will be 0. 

Prioritylncrement. This field contains the number that will be subtracted from 
the generator priority when the note reaches the sustain segment. If you allocate 
all generators at the same priority, this will force older notes to be stolen first, which 
is usually what you want to happen, 

PitchBendRange. This Held contains the number of MIDI semitones the pitch of 
the wavelorm will lie raised when the pitehwheel reaches 127. PitehBendRange can 
be I, 2. or 4. 
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VibratoDepth. This field contains the amplitude of a triangle-shaped wave that 
modulates the main waveform for the note. It can range from (no vibrato) to 127 

VibratuSpeed. This field controls the frequency of the vibrato modulation and can 
range from to 255. The exact frequency depends on the update rate passed to 
NSStartup. 

AWaveCount. AWaveCount is a byte containing the number of wave definitions 
(I to 255) in the AWaveUst field for the first oscillator used by the generator. 

BWaveCount. BWaveCuunt is a byte containing the number of wave definitions 
(1 to 255) in the BWavelist field for the second oscillator used by the generator. 

AWaveList and BWaveList. There are two wavelists, one for each oseillator in the 

generator used to play a note. Using wavelists, you can assign different waveforms 
to different semitone ranges, change the pitch slightly, and set the DOC operating 
mode. All the waveforms must be loaded into DOC RAM before the note is played. 
Each entry' in a wavelist has the following format: 

TopKey (byte) Semitone limit 

Wave Address byl DOC Address value 

Was ('Size {byte) DOC Waveform value 

DOCMode (byte) DOC Oscillator Control value 

RelPitch rd) Pitch tuning factor 

TopKetj. TopKey represents the highest MIDI semitone to which the waveform 
described by the wavelist applies The lowest applicable semitone is the TopKey 
value for the previous wavelist entry plus 1. Wavelist entries must be in increasing 
TopKey order, and the TopKey for the last entry must be 127 (the highest MIDI 
semitone allowed). 

WaveAddretat. This value indicates fche starting page of the waveform in the DOC 
MM area. The Note Synthesizer puts this value directly into the DOC Address 

register. 

WaveSize, This code represents the Address Table and Resolution for the DOC 
oscillator. The Note Synthesizer stores this value in the DOC Waveform register 

DOCMode. This value is placed directly in the Oscillator Control register. As 
mentioned earlier in this chapter this register controls the output channel number, 
oscillator Interrupts, operating mode, and halt/pky status, When using the Note 
Synthesizer, you normally want the oscillator to be running in free-run mode in 
channel #0 with no interrupts, so the DOCMode byte is $00, It is also common to 
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halve the first oscillator run in swap mode ($06) for the attack, so that it will swap 
to the second oscillator operating in free-run mode tor the rest of the note, [n this 

situation, the second oscillator initially has a DOCMode of $01 i free- run, but halted); 
its hall bit is cleared automatically by the DOC when the swap takes place. 

RelPitch. This number is used to change the pitch oJ a waveform in a minor wav. 
The low-order byte ts in units of 1/256 semitone; the high-order byte is a two s- 
complement signed number representing whole semitones. RelPitch is normally set 
to 0. 

Turning off a Note 

When it is time to turn off a note, call the NoteOff function. This forces the Note 
Synthesizer to go directly to the release Stage in the notes ADSR envelope. For 
most instruments, this causes the volume of the note to quickly decay to a zero 
level. When this happens, no more sound is heard, the generator used for the note 
is automatically deallocated, and its priority is set to 0. 
Here is how to call XoteOff: 

PushWord GenNum ".Generator number for the note 

PushWord Semitone -.Semitone value for the note 

..NoteOf f 

II you want to turn off all notes at once, use AllNotesOff It requires no parameters. 
The Note Synthesizer also has a function for explicitly deallocating a generator — 
DeallocGen: 

PushWord GenNum ; genera tor number 

_Dea 1 iocGen 

This function sets the priority oi the generator to and halts its two oscillators. You 
should not need to use DeallocGen, because the Note Synthesizer calls it for you 
automatically when the note volume goes to 0, 

Shutting Down the Note Synthesizer 

When you are finished with the Note Synthesizer, call NSShutDown {no parame- 
ters). It automatically turns off all generators used by the Note Synthesizer, so there 
i.s no need to call AllNotesOff or DeallocGen first 

PLAYING A SONG 

The SONG program in listing 1 1-4 shows how to use the Note Synthesizer to play 
the series oi notes that make up a song. Notes are denned for two distinct musical 
tracks, and the program combines these tracks to play the song. In the example, 
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the same instrument and waveform is used for each track, but with a little extra 
effort you could assign a different instrument unci waveform to each track. 

Each track in the song is defined by a series of four-word note records, each of 
which defines the pitch of a note, its volume and duration, and the time interval 
between the start of the note and the start of the next note. (You can play several 
notes at the same time in one track by specifying a interval) The end of the track 
is marked bv four consecutive words, Here is the exact format of a note record: 



■ MIDI semitone: to 127 

• MIDI volume: to 127 

• note duration: in units of 1/30 second 

• note interval: in units of I 30 second 



Each unit of note duration or note interval is 1730th of a second, because the update 
rate passed to NSStartup is 30 Hz* If you use a different rale, you must change the 
duration codes accordingly. 

To add another musical track to the SONC program, first increase the value of 
TrackMax by 1 and place a pointer to the brack's note table in the track table that 
follows Track Max. Finally, insert the note table for the track and terminate it with 
four zero words. When you reassemble the program, the new track will be played 
with all the others. 

The portion of the SONC. program that does most of the work is the Sequencer 
subroutine. It is called at the update rate (30 limes per second) and is responsible 
for keeping track of the status of all notes being played and for turning notes on and 
off when necessary, 

When Sequencer first gets control, it decrements the note interval counters for 
each track; these counters were originally set equal to the value stored in the record 
for the last note played in each track. (The program puts Is in these counters when 
it first starts up to force the first notes in each track to be played right away.) II a 
counter becomes 0, it is time to play the next note in the track, so Sequencer calls 
the NextNote subroutine to get the next note record from the list. It then turns the 
note on by allocating a generator with AllocGen and then calling NoteOn, It also 
adds 8 to the track's note pointer so that it points to the next note record. 

After Sequencer turns on any notes that are ready to be played, it decrements 
the duration counters for all generators that arc still playing notes. These counters 
were initialized when the note was first turned on. If a counter becomes 0, it calls 
Note Off to release the note. The generator is automatically deallocated when the 
volume goes to 0. 
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REFERENCE SECTION 

Table Rll-I: The Major Functions in the Sound Manager Too] Set (SOS) 



Function Name 


Function 
Number 


Stack 

Parameters 


Description of 
Parameter 


FFGeneratorStatus 


111 


result |A\ 


Generator status word 






GcnNum (W) 


Generator number 


FFSoundDoneS tatus 


$14 


result (W) 


= playing/SFFFF = stopped 






Gen Nu in (W 


Generator number 


FF Sounds tatus 


$10 


result (W) 


Generator status word 


FFStartSound 


SOE 


Gen Mode (W) 


Generator (high), mode (low) 






PararnBloek ;Li 


Ptr to parameter block 


FFStopSound 


$0F 


GenMa.sk W 


Generator mask 


GetSoundVolume 


$0C 


result (W) 


Volume setting 






Gen \ urn (W) 


Generator number 


GetTabJe Address 


SOB 


result (L) 


Ptr to low-level DOC table 


ReadRam Block 


SOA 


DestPtr (L) 


Ptr to destination address 






DOCStart (VV) 


Starting address in DOC RAM 






Count (W) 


Size of wave to read 


SetSoundMIRQV 


$12 


MasterlRQV (L) 


Ptr to new sound IRQ handler 


SetSoundVolume 


$0D 


VolSetting (W) 


Volume level 






GenNum (W) 


Generator number 


SetUserSoundlRQV 


$13 


result (L) 


Old user IRQ handler 






NewIRQV (L) 


Ptr to new user IRQ handler 


Sounds hut Down 


$03 


[no parameters] 




SoundStartup 


$02 


DPAddr (W) 


Address of 1 page in bank 


Writ eRam Block 


$06 


SourcePtr iU 


Ptr to start of data 






DOCStart (W) 


Starting address in DOC RAM 






Count (W 


Size of wave to write 
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Tabic Rll-2: Sound Manager Error Codes 



Error 
Code 



Description of Error Cond i tion 



$0810 
$0811 

$0812 



S0815 

son 17 

$0818 



The system does not contain a DOC chip. 

The specified DOC address is invalid 

The Sound Manager has not been initialized, 

The generator number is invalid. 

The synthesizer mode is invalid. 

The generator is busy. 

The master IRQ vector has not been assigned. 

The Sound Manager has already- been started up. 



The Sound Manager can al&o return Memory Manager and ProDOS 16 error codes. 



Table Rli-3: 


The Major Fun 

Function 
Number 


I'tions in the Note S) 


nthesizer Tool Set <$iy} 


Function 

Name 


Stack 
Parameters 


Description oj 

Parameter 


AllNotesOff 


$0D 


[no parameters] 




AllocGen 


909 


result (W) 


Generator number 
allocated 






Gen Priority i\Vi 


Generator priority 


DeallocGen 


S0A 


GenNum (W) 


Generator number 


NoteOff 


$0C 


GenNum (VI 


Generator number 






Semitone (W) 


MIDI semitone 


NoteOn 


SOB 


GenNum i\Vi 


Generator number 






Semitone (W) 


MIDI semitone 






Volume (W) 


Volume 






InstrumcntPtr (L) 


Ptr to instrument definition 
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Function 


Function 


Stack 


Description oj 


Name 


Number 


Parameters 


Parameter 


NS Shut Down 


$03 


[no parameters] 




\S Startup 


$02 


UpdateRate (W) 


Update rate code 






UserUpdate (L) 


Ptr to update handler 



Table Rll-4: 


Note Synthesizer Error Codes 


F,rror 




Code 


Description of Error Condition 


$1901 


The Note Synthesizer has alreath been initialized. 


$1902 


The Sound Manager has not been initialized. 


$1921 


No generators are available. 


$1922 


Invalid generator number. 


$1923 


The Note Synthesizer has not been initialized. 


$1924 


The generator is already being used, 



Table Rll-5: 


Useful Functions in 


the 


Miscellaneous Tool Set ($03) 


Function Same 


Function 
Number 




Stack Description of 
Parameters Parameter 


SysBeep 


S2C 




[no parameters] 
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Listing 11-1; Creating Simple Waveforms 



(a) Cresting and loading a sine wave: 



LoadSine 



ANOP 

PushPtr WaveForm 
PushWord 'S0000 
PushWord #»100 
_Wr l teRamBlocfc 
RTS 



^Pointer to waveform 
;Starting DOC address 
;Number of bytea 



This is a sine wave. The values were calculated from 
the formula Y = 1 27 * SIN{X * 2 • Pl/256) * 128 where 
PI = 3.14156. 



WaveForm 



ANOP 



DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 

DC 



11 M28.131 ,134,137.140,144,147,150,153,156,159,162,165,168,171 

11 '177 179.182,185,188,191 ,193.196,199,201 ,204,206 ,209 ,211 ,213 

11 -218,220,222,224,226,228,230,232,234,235,237,239,24 0,241 ,243 

11 1245,246,248,249,250,250,251 ,252,253,253,254,254,254,255,255 

[1 '255 255,255,255,254,254,254,253,253,252,251 ,250,250,249,248 

M '245,244,243,241 ,240,239,237,235,234,232,230,228,226,224,222 

11 "218,216,213,211,209,206,204,201 , 199, 196, 193, 191 , 188 , I 85 , 1 82 

11 '177,174,171 ,168,165,162,159,156,153,150,147,144,140,137,134 

11 '128,125,122,119,116,112,109,106,103,100,97,94,91 ,88,85,82' 

II '79,77,74,71 ,68,65,63,60,57,55,52,50,47,45,43,40' 

H '38,36,34,32,30,28,26,24,22,21 ,19,17,16,15,13,12' 

II' 11, 10, 8, 7, 6,6,5, 4, 3,3, 2, 2, 2, 1,1,1' 

11 11 r 1 ,1 ,1 ,2,2,2,3,3,4,5,6,6,7,8,10' 

[1 -11 ,12,13,15,16,17,19,21 ,22,24,26,28,30,32,34,36' 

II •38,40,43,45,47,50,52,55,57,60,63,65,68,71 ,74,77' 

M '79,82,85,88,91 ,94,97,100,103,106,109,112,116,119,122,125' 



,174' 

,216' 
,244' 
,255' 
,246' 
,220' 
,179' 
,131 ' 



(b) Creating and loading a triangle wave: 
LoadTnang ANDP 





SEP 


#$20 




LONGA 


OFF 




LDX 


#0 




LDA 


#*4D 


PutWavel 


STA 


WaveForm, X 




INC 


A 




INK 






CPX 


#t80 




BNE 


PutWavel 



;8-bit accumulator 

;5tart of triangle 

ifiiove up 
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PutWaveS 


STfl 


WaveForm, X 




DEC 


A 




INX 






CPX 


'$100 




BNE 


PutWave2 




REP 


#$20 




LONGA 


OFF 



;move down 



;16-blt accumulator 



PushPtr WaveForm {Pointer to waveform 

PushWord #$0000 ^Starting DOC address 

PushWord #$100 ;Number of bytes 
_WriteRamBlock 

RTS 

WaveForm DS 256 

Listing M-2: The CONVERTER Program 



* This program shows how to digitize an incoming » 

* analog signal through the Ensoniq DOC • 





KEEP 


ANALDG 




MCOPY 


ANALOG. MAC 


Deref Loc 


GEQU 


*00 


TablePtr 


GEQU 


*04 


Sampl e 


GEQU 


$08 



;Used for dereferencing handles 
{Pointer to low-level table 
{Pointer to start of buffer 

Converter START 

USING GlobalData 

PHK 

PLB {Program bank ■ data bank 

JSR Startup -.Start up the tools 

; Allocate a 32K buffer for the samples: 

PHA -.Space for result (handle) 

PHfl 

PushLong *$80QQ {Reserve 32K block 

PushWord MylD ; ID tag for memory block 

PushWord #*C00Q -.Locked, fixed 

PushLong #$00 ; [ no meaning] 
_NewHand le 
PopLong DerefLoc 
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LDA 


[Deref Loc 1 




STA 


Samp 1 e 




LDY 


*2 




LDA 


[ Deref Loc ] 


, V 


STA 


Sample'2 





-.Convert handle to pointer 



, Get address of low-level subroutine table; 

pHA -.space for result 

PHA 

_GetTableAddress sO«t address 

PopLong TablePtr 

-. i^.*„ ,Hrir«^ of the DOC read subroutine (first 
j Store the 3-byte address o? - u instruction: 

• entry in the table) in the operand of the JSL 



LDA 


[TablePtrl 


STA 


JSL_Patch*1 


LDY 


#1 


LDA 


CToblePtr ] ,Y 


STA 


JSL_Patch+2 



JS R DoSample iStart sampling 

, [insert code here to save sample to disk, etc.! 
jMP ShutDown ^Finish up 

, This subroutine samples the analog Ltp.it line until 
,8000 samples have been taken or until ESC is pressed 
The sample »it. is returned in the Y register. 



DoSample ANOP 



SEP 

LQNGA OFF 



g$2 Q i8-bit accumulator 



LDV #0 initialize buffer pointer 

;Save pointer 

#$E2 ;flnalog-to-Digital register 



GetSample PHY 
LDX 

; the program: 

p Ly ;Get pointer 
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STA 


l Samp 1 e ] 




JNY 






CPY 


*t8000 




BEQ 


Exit 





jSave the sample in buffer 

1 B u m p buffer pointer 
;At 32K limit? 
; V r? , so bra nch 

; Use a delay loop like this to adjust the sampling rate. 

; A value of 475 for X gives a rate of about 1 000 samp lea /second . 

LDX *47S ;Delay counter 

Delay DEX 

BNE Delay 

; Check keyboard for ESC (see chapter 12): 

;Check keyboard 

;Branch if nothing there 

{Clear keyboard strobe 

;Esc? 

jNo, so get next sample 

Exit REP *S20 ;Back to 16-bit accumulator 



END 



LDA 


SE0COOO 


BPL 


Ge t Sample 


STA 


SEOC010 


CMP 


#$9B 


BNE 


Ge tSample 


REP 


*$20 


LDNGA 


DN 


RTS 





* Start up the standard tool sets • 
iitt(ftt*itiiitiittiittiittttti*tii 

StartUp START 

USING GlobalData 



_TLStartup 
_MTStar tup 

PHA 

_MMS t ar t up 

PLA 

STA My ID 

* Get one page in bank $00 for SoundS tar tup : 

PHA ;Space for result (handle) 

PHA 

PushLong #1100 {Reserve one page 

PushWord PlylD ;ID tag for memory block 

PushWord #«C005 ;Locked, aligned, fixed 

PushLong **00 ;... in bank $00 

_NewHandle 
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; Dereference the handle: 

PopLong DerefLoc 
LDA [DerefLoc! 

PHA 
_SoundStar tup 

RTS 

-, Shut down all the tool sets 
; and leave the application: 

ShutDown ENTRY 

_SoundShut Down 

PushUlord MylD 
^MMShutDown 

_MTShutDown 
_TLShutDown 

Quit QuitParms 



(Get direct page address 

;Pu5h direct page address 
(Start up the 5ound Manager 



JuitParms DC 
DC 



M'Q' 
12' 0' 



END 



GlobalData 


DATA 




My ID 


DS 

END 


2 


Listing 11-3: 


An E 


xainple of an 1 


1 nst rumen t 


ANDP 






DC 1 


1 '127,0,127 




DC 


1 M20 ,20,1 ' 




DC 


1 '120,0,0' 




DC 


1 ' , , 1 1 ' 




DC 


1 '0 ,0 .0 1 




DC 


1 '0,0,0' 




DC 


t '0,0,0' 




DC 


11 '0,0,0' 




DC 


II '3' 




DC 


t 1 '32' 




DC 


11 '2' 



(program ID tag 



;5harp attack to max volume 

;5low decay 

; Sustain at same level 

; Re lease to zero 

; t unused stage ] 

1 [unused stage ] 

; [ unused stage I 

; tunused stage! 

;Release stage number 

(Priority reduction at sustain 

-,Pi tchbend 
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DC 


1 ' 80 • 




DC 


[1 '90' 




DC 


1 '0' 




DC 


1 M i 




DC 


1 ' 1 ' 


AUIaveList 


DC 


1 M27' 




DC 


1 '100' 




DC 


1 '0' 




DC 


1 f 6' 




DC 


2 1 0' 


BUaveLiit 


DC 


1 M27' 




DC 


1 ' 101 ' 




DC 


1 '0 1 




DC 


1 ' l ' 




DC 


2'0' 



Listing 1 1-4; Th«* SO\c; Program 



; Vibrato depth 

;Vibrato frequency 

; [ spa r e ] 

;Number of entries in AWavelist 

^Number of entries in BWavelist 

; T o p K e y 

;Starta at page J00 in DDC RAM 

;Waveform register: one page 

;Mode: swap to B, playing 

;Mo pitch change 

; TopKey 

jStarts at page $01 in DOC RAM 

; Waveform register; one page 

• r Mode: free-run, halted 

;No pitch change 



This program shows how to construct a simple • 
tune using the Note Synthesizer, * 





KEEP 


SONG 




ffCQPY 


5QNG.MAC 


NotePtr 


GEQU 


$0 


1 n t erva 1 


GEQU 


420 


Song 


START 






USING 


GlobalData 




USING 


TheNotes 




USING 


Instrument 




PHK 






PLB 






TDC 






STA 


MyDP 




JSR 


Startup 




J5R 


MaieWave 



^Pointers to each note track 
;time until next note begins 



;Program bank ■ data bank 
; Save current direct page 

;Load wave into DOC RAN area 
; Get the Note Synthesizer up and running: 

SE I ;No interrupts until we're ready 



PushWord #75 
PushPtr 5equencer 
_NS5tartup 



■ T 30 Hz update rate 
;Interrupt handler 
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■» Hpre 13 the main program loop: 

KeyWait PRINTLN 'Press any key to itart the song (E5C to cancel; 



PHA 

PushWord #0 
_ReadChar 

PLA 



;0 * no echo 



AND 

CMP 
BEQ 



#*7F 
<r*1B 
ShutDown 



Convert to ASCI I 
E5C pressed? 
Yes, so bail out 



Initialize the pointers to the sound tables and fix 
things up so that the first note in each track is 
played right away: 





L E V 


*Q 




LDX 


#0 


DoTables 


LDA 


TraekMax+2,X 




STA 


NotePtr ,X 




LDA 


TrackMax*4,K 




STA 


NotePtr«2 T X 




LDA 


#1 




STA 


Interval , X 




INX 






INX 






INX 






INX 






I NY 






CPY 


Trac kMax 




BNE 


DoTables 




CLI 






BRL 


KeyWait 



;Transfer track pointer to d,p. 



;(Causes 1st note to be played] 
;. Move to next entry 



;Done all tracks? 
;No, so branch 

; Allow synthesizer interrupts! 



; Shut down all the tool sets 
; and leave the application: 



Shu t Down 



„N5Shu tDown 
.TextShutDown 
_SoundShu tDown 
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PushWord MylD 

_MM5hutDown 

_MTShutDown 
_TLShutDown 

_Quit QuitParms 

QuitParms DC I4'Q r 
DC 12'0« 

END 



■ This subroutine gets control after a Note Synthesize 
• interrupt. Interrupts occur 30 t lines /second . 

Sequencer START 

USING Instrument 
USING GlobalData 
USING TheNotes 



PHB 
PHK 
PLB 

PHD 
LDA 
TCD 



MuDP 



• t A I low absolute addressing 
; Switch to application's d.p. 



; Check to see if it's time to play the next note; 





LDX 


#0 


DoTrack 


DEC 


1 nterval 




BNE 


NextTrack 




PHX 






JSR 


NextNote 




PLX 




NextTracfc 


TDC 

CLC 






ADC 


*4 




TCD 






I NX 






CPX 


TrackMax 




BNE 


DoTrack 



;Reduce time to next note 

;Branch if not time to play next note 



;Get next note 



•,Keep the d.p. in step with 
; the current track . 



;Done all tracks? 
;No, so branch 
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LDX 


#13*2 


GenChec k 


LDA 


Durat ion , X 




BEQ 


Next Gen 




DEC 


Durat ion , X 




BNE 


NextGen 



; Turn off all generators whose notes are done; 

;ls this note playing? 
-, No , so branch 

;Reduce duration counter 
; Branch if more to come 

PHX -Don't destroy X 

LDA Generator, X 

PHA 

LDA Semitone.X 

PHA 

_NoteOff ;Turn off the note 

PL); ; Restore X 

NextGen DEX - t Movc to next generator 

DEX 
BPL GenCheck 

p(_Q ;Restore direct page 

PLB -,Restore data bank 

RTL 

; Get the next note in the note table: 

NextNote LDA [NotePtr] -.Get next semitone 

BNE GetGen ;Branch if note defined 

RT5 

GetGen PHA ;Space for result 

PuahWord #127 ^Generator priority 

_AllocGen ;Allocate a generator 

pi_A -,Get generator number 

PHA "»( kee P a C0 Py on stack) 

PHA ;(..« and another) 

ASL A * t x2 for array position 

TAX 

PLA 

STA Generator, X ;Store generator number 

LDA [NotePtr] 

STA Semitone, X ;Store note semitone 

LDY *4 

LDA [NotePtr], Y 

STA Duration, X ;Store note duration 
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LDY 

LDA 
STA 



#6 

(NotePtr J ,¥ 

I nterva 1 



;Store time to next note 



; Sound the note by calling NoteOn (the generator 
', number 15 already on stack); 



[NotePtr] 



LDA 

PHA 

LDV 

LDA 

PHA 

PushPtr Instrument 

^NoteOn 



*2 

I NotePtr] ,Y 



; Semi tone 



; Volume 

; I nst rument 

; Start sounding the note 



* Bump the pointer to the next note record: 



CLC 




LDA 


NotePtr 


ADC 


#8 


STA 


NotePtr 


LDA 


] nterva 1 


BEQ 


NextNote 



RTS 



Generator 


DS 


14*2 


Semitone 


DS 


14*2 


Dura t ion 


DS 


14*2 



; Add size of note recon 



;Delay before next note? 

;No, 50 get next note right now 



Generators used by active notes 
Semitones used by active notes 
Durations of active notes 



END 



* This data segment defines the notes • 

• for the tune we will play. • 

TheNotes DATA 

! These are the MIDI codes for semitones: 



o5 
06 



EQU 
EQU 



84 
96 



;Dctave 5 base 
;Dctave 6 base 



i Semitone offsets from the start of each octave: 



c 


EQU 


C 


Cs 


EQU 


1 


D 


EQU 


2 


Ds 


EQU 


3 
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E 


EQU 


4 


F 


EQU 


5 


Fa 


EQU 


E 


G 


EQU 


7 


Ga 


EG. 


1 


A 


EQU 


9 


Qb 


EQU 


10 


B 


EQU 


11 



iThis s table of pointers to each music track: 



TrackMax DC 
DC 
DC 



I2'2' 

I4»Track1 ' 
I4'Track2' 



;Number of tracka 
; Pointer to track 1 
;Pointer to track 2 



j Here are the note definitions. Each is made up 

; of four words describing the semitone, volume, 

; duration, and the interval until the next note. 

; A zero semitone marks the end of the list. 

1 This is the definition for "Happy Birthday": 

Trackl ANDP 



vl 



EQU 



127 



iMelody volume 



DC 


I 'oS+C.vl .4,4' 


DC 


] »o5+C,v1 ,4,4' 


DC 


I »oS*D,v1 ,8,8' 


DC 


1 'eS+C.vl ,8,8' 


DC 


I 'o5*F,v1 ,8,8' 


DC 


I 'oS»E,v1 ,15,15' 


DC 


1 'o5*C,v1 ,4,4' 


DC 


I'oS+C.vl ,4,4' 


DC 


1 'o5*D,v1 t 6,8' 


DC 


I 'o5+C,v1 ,8,8" 


DC 


I 'o5*G,v1 ,8,8* 


DC 


Po5*F,v1 ,15,15' 


DC 


I 'o5 + C,v1 ,4,4' 


DC 


I 'o5+C.v1 ,4,4' 


DC 


I 'o6+C,v1 ,8,8' 


DC 


I 'o5+A,v1 ,8,8' 


DC 


I 'o5+F ,v1 ,8,8' 


DC 


I 'o5*E t v1 ,8,8' 


DC 


I 'o5*D,v1 ,15,15" 


DC 


I ' o5*fls , v1 , 4 , 4 • 


DC 


[ »o5+As ,v1 ,4,4" 


DC 


1 •o5*A,v1 ,8,8' 
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DC l'o5+F,v1 ,8,8' 

DC I 'o5+G,v1 ,8,8* 
DC I r o5*F,v1 ,15,15' 

DC I'D, 0,0,0' ;End of note table 

; Track2 contains the accompanying chords: 



Track2 


ANQP 




v2 


EQU 


127 ;Chord volume 




DC 


1 ' o5*F,0 ,8,8' ; (do nothing) 




DC 


I 'o5+F,v2,24,0' 




DC 


[ «oS + A,v2,24,0' 




DC 


I 'o6+C,v2,24,24' 




DC 


I 'o5*E,v2,23,0' 




DC 


I 'o5*A5,v2,23,0' 




DC 


I 'o6*C ,v2,23,23' 




DC 


I <o5+F,v2,16,Q f 




DC 


I 'o5*A,v2,1G,Q' 




DC 


I 'o6 + C,v2,16,16' 




DC 


I , oS + E 5 v2 1 8 1 0' 




DC 


1 '05 + ^5^2,8,0' 




DC 


I ' o6+C, v2,8>8' 




DC 


I 'o5+F,v2,23,0' 




DC 


I 'o5+A,v2,23,Q' 




DC 


! «o6+C,v2,23,23' 




DC 


1 ^o5*F,v2,24,0' 




DC 


I »o5*A,v2,24 1 0' 




DC 


I 'oG+C,v2,24,24' 




DC 


I 'o5+£,v2»31 ,0' 




DC 


1 'o5*A5 ,v2,31 ,0' 




DC 


I »o6+C,v2,31 ,31 ' 




DC 


I 'o5 + F ,^2,16,0' 




DC 


1 «o5+A t v2 v l6,D' 




DC 


[ •oG+C 1 v2,16,16 l 




DC 


1 >o5*E,v2,8,0' 




DC 


I 'o5+As ,v2,8,0' 




DC 


I l o6+C,v2,8,8 l 
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DC 
DC 

DC 

DC 

END 



1 'o5+F,v2,1S,Q' 
I '05^^2,15,0' 
I 'o6+C,v2,15,15' 



I '0,0,0,0' 



;End of note table 



* This data defines the instrument which ♦ 

* is used to play the song. 



Instrument DATA 

dc 
dc 
dc 

dc 
dc 
dc 

dc 

dc 

fir 

dc 
dc 
dc 

dc 
dc 

dc 
dc 

Wdvd dc 
Wave? dc 

END 



il ' 


S7F 


0,64 


i1 


0,0 


IC2' 


11 


0,0 


0' 


11 


0,0 


D' 


11 


0,0 


0' 


11 


0,0 


,0« 


1 1 


0,0 


,0' 


i1 


0,0 


,0' 


H 


•1 ' 




11 


•32' 




i1 


IQ,1 




il 


'0' 




i1 


'0' 




il 


1 ' 




i ' 


' 1 • 




11 


'1 < 





Sharp attack 
Sustain with slow decay 
(the other six segments 
are unused) 



-.Segment number for release 

^Generator priority 

;Pitch bend range 

-.Vibrato 

; Vibrato speed 

; [unused] 

;Number of waveforms for osc *1 
^Number of waveforms for osc *2 



11 '127,0,0,0,0,0' 
i1 ■127,0,0,0.0,0' 



Load a waveform into the first page of DOC RAM * 



Ma ketJave 



START 



Transfer the waveform to the DOC RAM: 



PushPtr WaveForm 
PushWord **0000 
PushWord #*100 
_Wr i teRamBlock 
RTS 



;Pointer to the wave 
-.Starting address in DOC RAM 
;Transfer one page 
;Do the transfer! 
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This is a sine wave. The values were calculated fron 
the formula Y = 64*S1M(X * 2-PI/2S6) * 120 where 



! PI 


- 3.14156. Th 


e zero base] 


me is given 


by the value »B0 . 






WaveF 


arm fiNOP 














DC I 


'128,130,131 


,133,134 ,136 


,137,139,140 


,142,144,145,147 


148 


150 


,151 ' 


DC 1 


'152,154 ,155 


.1 57, 158, 160 


161 ,162,164 


,165,166,167,169 


170 


171 


,172" 


DC I 


1 1 73,174,175 


,175,177,178 


179,180,181 


,182, 183,184, 184 


185 


186 


,187' 


DC I 


' 187, 188,188 


,189,189,190 


190,190,191 


,191 ,191 ,192,192 


192 


192 


,192" 


DC I 


•192,192, 192 


,192,192,192 


191 ,191 ,191 


,190 ,190,190,189 


189 


188 


188' 


DC I 


'187,187,186 


185,184,184 


183,182,181 


,180,179,178,177 


176 


175 


174' 


DC 1 


•173,172,1 71 


170,169,167 


166,165,164 


,162,161 ,160,158 


157 


155 


154' 


DC I 


•152,151 ,150 


148,147,145 


144,142,140 


139,137,136,134 


133 


131 


130' 


DC 11 


M2B ,126,125 


123, 122,120 


119,117,1 16 


114,112,111 ,1 09 


108 


106 


105' 


DC 11 


'104,102,101 


99,98,96,95 


94,92,91 ,90 


89,87,86,85,84* 








DC 11 


'83,82,81 ,80 


79,78,7 7.76 


75,74,73,72 


72,71 ,70,69' 








DC 11 


'69,68,68,67 


67,66,66,66 


65,65,65 t 64 


64 ,64,64 ,64' 








DC 11 


•64 ,64,64,64 


64,64,65,65 


65,66,66,66 


67,67,68,68' 








DC F1 


'69,69,70,71 


72,72,73,74 


75,76,77,78 


79,80,81 ,82' 








DC 11 


.'83,84,85,86 


87,89,90,91 


92,94 ,95,96 


98,99,1 01 ,102' 








DC 11 


'104,105,1 06 


108,109,111 


112,114,116 


117,119,120,122, 


123, 


125 


126' 



END 



• Start up the standard tool set: 

Startup START 

USING GlobalData 



DeRefLoc EQU 



»0 



;Used for dereferencing handle 



_TLStartup 
_MTSt a r tup 

PHA 

_MM5tar tup 

PLA 

STA My ID 

PushPtr ToolTable 

_LoadTools ;Load the Note Sequencer 

• Get one page in bank $00 for SoundS tar t up : 

;Space for result (handle] 



PHA 
PHA 

PushLong #*100 
PushWord MylD 



;Reserve one page 

;ID tag for memory block 
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PushWord #*C00S '.Attributes — locked, aligned, fixed 

PushLong #$00 ■, . , , in bark tOO 



_NewHandle 
; Dereference the handle: 





PLA 
STA 
PLA 

STA 
LDA 




Deref Loc 

Deref Loc + 2 
[DerefLocl 




PHA 








Soun 


dSt 


ar tup 




_Tex 


tst 


a r tup 




RT5 






ToolTable 


DC 
DC 

END 




12U ' 
I2'25,*0QQQ 


GlobalData 


DATA 






MyDP 
My ID 


DS 
DS 




2 
? 



END 



;Get direct page address 
;Push direct page address 
*,Start up the Sound Manager 



;.One tool set to load 
;Note Sequencer tool set 



;program r 5 direct page 
; program ID tag 



Reference Section 433 



CHAPTER 12 



Using the Text 
Tool Set 



The purpose of the Text Tool Set (tool set 12) is to give programs running in 65816 
native mode anywhere in memory an easy way to direct character output or input 
operations to an I/O device in a slot or port. Doing this without the Text Tool Set 
is awkward, because these types of I/O devices must be accessed while in emulation 
mode and while the data bank and direct page registers are set to 0. (These 
restrictions stem from the need to maintain compatibility with He software and 
hardware.) The functions in the Text Tool Set take care of saving the current mode 
and registers, switching you to the proper ones for the I/O operation, and restoring 
the original values on exit. 

The three main uses of the Text Tool Set are to read character input from the 
keyboard (without using the Event Manager}, to display characters on the G$'s 80* 
column text screen (instead oJ the super high-resolution screen used by QuickDraw 
II), and to send data to a printer. Although these uses will be emphasized in this 
chapter, the Text Tool Set is general enough to work with any character device in 
any slot or port, or with custom FLAM -based I/O drivers. 

The start-up and shut-down functions for the Text Tool Set are TcxtStartup and 
TextShutDown. Neither one requires parameters or returns results. 

LOGICAL DEVICES AND MASKS 

The functions in the Text Tool Set deal with three logical I/O devices: 

* An input device 

* An output device 

* An error-output device 

The error-output device is the device to which an application can send error mes- 
sages or status reports without interfering with what the primary output device 
receives. 
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You can assign each logical device to any slot or port on the cs that interfaces 
with a character-based I/O device. In a typical hardware configuration, the choices 
for output devices are a printer in port #1, a modem In port #2, and an 80-column 
video screen in port #3. The input device is usually the keyboard (it is supported 
through the video screen port #3) or the modem. in port #2. The default device 
assignment for all three devices is port #3. 

Device Driver Types 

Yon can assign a specific type of device driver to each of the three logical devices 
with Text Tool Set functions. The three choices are; 

• BASIC] driver {driver type code 0) 

• Pascal 1.1 driver (driver type rode I) 

• RAM-based driver (driver type code 21 

A BASIC driver is one which adheres to Apples Applesoft protocol for initialization, 
input, and output. According to this protocol th< entry points for the driver must 
he as Follows; 

• SCnOO (initialization) 

• SCiiO.5 (input; character returned in accumulator) 

• SCnOT (output; character in accumulator) 

where n is the port (or slut number. The gs's two serial ports and the 80-column 
video port support this protocol. 

A Pascal 1.1 driver uses a different protocol, first developed for the Apple UCSD 
Pascal operating system. Such drivers contain a look-up table at $CnOD to $Cnl3 
that contains the low-order bytes of the addresses of the subroutines for handling 
initialization, input, output, status, device control, and device interrupts The high- 
order bytes are always SCn. Any driver with a value of $38 at $Cn05 and a value of 
SI 8 at location $Cn07 supports the Pascal 1.1 protocol. This includes the serial ports 
and video port on the c.v 

You can also use your own RAM-based drivers if you wish. Such drivers must 
support five fundamental subroutines: initialization, input, output, status, and con- 
trol- The addresses of these subroutines must appear in a table at the beginning of 
the driver. Each address is a3-byte absolute address (low-order bytes first, as usual). 

The cs calls RAM-based driver entry points with a JSL instruction while in full 
native mode, so driver subroutines must end with an RTL instruction. Character 
transfers between the tool function and the driver use the low-order 8 bits of the 
accumulator 
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Because' the cs internal character I/O ports support both the BASIC and Pascal 
protocols, you can assign a driver type code of or I to the logical devices. The 
default driver type is BASIC, although the default is only set up when ProDOS 16 
first starts up. There is no way for an application to tell what the driver type will 
be when it gets control, so the application most always explicitly set the driver type 
using the techniques described below. 

Data Masks 

When handling I/O operations involving ASCII-encoded text, it is important to set 
the high-order hit (bit 7) properly. The ASCII standard does not use this bit, so 
many peripheral devices expect it to be 0. Most printers, for example, will want 
the high hil off unless you are trying to print special symbols that are assigned to 
codes above 571- The cs BASIC 80-colunm text screen driver, on the other hand, 
insists on receiving characters with the high-order bit set, and keyboard input 
subroutines on Apple II computers traditionally return characters with the high- 
l bit set. 

The Text Tool Set always manipulates the bits in a byte you send or receive by 
logically AN Ding the byte with an AND mask and then Logically QRing the result 
with an OK mask (unless you are using a RAM-based driver). There are AND and 
OK masks for each of the three logical devices, 

On initialization, the AND masks for the input, output, and error-output devices 
are set to $FF and the OR masks are set to $80. This forces the high-order bit of 
incoming and outgoing data to 1 and is the format expected by BASIC, the default 
driver type. 

When sending data to a printer, you usually want to dear the high-order bit of 
outgoing data to 0. To do this, change the output AND mask to $7F and the OR 
mask to $00 with the SetOutGlobals function: 

PushWord #I7F ;The new AND mask 

PuahWord #*00 ;The new OR mask 

„5etDutGlobal5 ;( r Setln, 5etErr) 



(Use SetlnGlobals and SetErrGlobals for the other two logical devk. 

When using an ImageWriter II printer, the state of the high-order bit is usuall. 
unimportant, because the ImageWriter II normally forces the high-order bit of 
incoming data to 0. If, however, you specifically enable recognition of this bit (with 
a special printer command: $1B $5A $00 $20), perhaps to allow printing of 
MoiiscTcxt icons that have codes from SCO to SDF, you do not want the high-order 
bit to be altered, Jn this situation, you would change the masks to $FF (AND) and 
$00 (OR) and use an AND #S7F instruction to specifically clear the high-order bit 
of a text character before printing it 

To determine the active AND and OR masks, use the GetlnGlobals (input device), 
GetOutGlobals (output device), and GefcErrGlobals (error output device) functions: 
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PHA ;space for AND mask 

PHA ; space for DR mask 

_GetOutGiobals ;(or Getln, GetErr) 

PLA ;Pop the OR mask (low byte) 

PL* ;Pop the AND mask (low byte) 

You might use these functions to save the exist in? masks SO that you can restore 
them when you exit your program. 

CHANCING ACTIVE DEVICES 

Before you begin performing character I/O operations, you must select your three 
active devices, initialize them, and select appropriate AND and OR masks. To select 
a device, use the SeOnput Device, SetOutput Device, and SetErrorDevice functions. 
Each requires two parameters: a device-type code word and a long word containing 
the port or slot number of (he device or the address of its RAM-based driver. 

For example, here is how to select die printer attached to port #1 as the active 
output device: 

PushWopd #0 ;0 = BA5IC driver type 

PuahLong #1 ;port 1 

_SetQutputDevice 

The first parameter pushed on the stack is the driver type code (use for a BASIC 
driver); the second is the port number. If you were using a RAM -based driver with 
the printer, the second parameter would be the address of" its subroutine address 
table. 

II you need to know what the currently active device is, use the GetlnputDcvice, 
GetOutputDevice, and CetErrorDevke functions: 



jSpace for device type 
;Space for slot number (long) 



PHA 
PHfl 

PHA 

.GetOutputDevice ;{or Getlnput, GetError) 

PopLong DutputPort ;Pop result 

PopWord DeviceType ;Pop result 

These functions each return a device type code? (word) and a slot number or a pointer 
to a KAM -based driver (long word). 

Initialization 

Once you have assigned an active device tor input, output, or error output, be sure 
to initialize it with InitTextDev. If you do not do so, it probably will not work 
properly. To use InitTextDev, pass it a word describing which device you wish to 

initialize: 
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PushWord TheDevice ;Device to initialize 
_InltTextDev 

The permitted values for TheDevice are (input device), 1 (output device), and 2 
(error-output device'. 

The effect of initialization varies from device to device. When you initialize the 
port #3 output device (the video screen) For output, for example, the screen clears. 

The subroutines shown in listing 12-1 illustrate how you might enable video port 
#3 for output, a printer in port #1 for output, and the keyboard for input 

SENDING CHARACTERS TO THE OUTPUT DEVICE 

There are five different ways you can send a character, or a group of characters, to 
the standard output device. The method you will use depends on how the textual 
information is arranged in memory. 

The five techniques are summarized below; 

WriteChar Send a single character 

WriteLine Send a sequence of characters that is preceded by a length byte; 

then send a Carriage Return code 
WriteStrmg Send a sequence of characters that is preceded by a length byte 

TextWriteBlock Send a specified sequence of characters 
WriteCString Send a sequence of characters that is terminated by a $00 byte 

(Similar functions exist for the error-output device; ErrWriteChar, ErrWriteLine. 
ErrWriteString, ErrWriteBloek. and ErrWriteC String. 

All these methods process outgoing characters by first ANDing them with the 
AND mask and then ORing them with the OR mask. 

Single characters are besl handled by WriteChar; 

PushWord #*00BD ;Pu5h with character in low byte 
_Ur i teChar 

To send a group of characters, you could make multiple calls to WriteChar, but this 
is slow and inefficient. If the text is in Pascal string format (that is, if it is preceded 
by a length byte), use WriteString instead: 

PushPtr MyStrmg ^Pointer to string 

_Wr i teSt r l ng 

its 

MyString STR 'This is a string 1 ;Text of string 

Use WriteLine in the same way if you want a carriage return code sent after the 

string is sent. 
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II the text is in C-string format (that is. if it is followed by a zero byte, with im 
length byte), use WriteCStrmg instead ofWriteString. There is no C equivalent to 
VVriteLine, however. 

Displaying text strings is such a common event that it is convenient to use macros 
to handle it. The PRINT macro in listing 12-2 sends a string specified in its argument 
to the output device. In a program, invoke PRINT by placing the string in single 
quote marks after the macro name: 

PRINT 'Print this 1 

If the string includes a single quote mark as part of the string, specify two single 
quote marks in a row. 

The PRINTLN macro, also shown in listing 12-2, is similar to PRINT but it uses 
VVriteLine instead of WriteString, As a result, it sends a carriage return code after 
the specified text string. 

To send any sequence of characters inside a large block of text, use Text- 
WriteBlock: 

PushPtr TheText ^Pointer to start of text block 

PushWord Offset ;Character to begin with 

PushUlord Count j Number of characters to send 
_TextWn teBLock 

TextWriteBIock sends the "Count" characters beginning at a position "Offset" bytes 
from the start of the text block pointed to by TheText. 

READING CHARACTERS FROM THE INPUT DEVICE 

There are three basic character reading functions in the Text tool set; ReadChar. 
ReadLine. and TextRcadBloek. The one you will use most often is ReadChar. 
because it grabs one character at a time from the keyboard (assuming port #3 is 
the input port), which is how most programs prefer dealing with keyboard input. 
Here is how to use it: 

PHA ■ space for result 

PushWord EchoFlag ;1 - echo, - don't echo 

_ReadChar 

PLA ;Pop character (low byte) 

The EchoFlag indicates whether you want to echo incoming data to the output 
device. In most situations, you will set it to 1 to enable echoing, 

ReadLine keeps reading characters until it receives an eud-ol-liue (EOL) char- 
acter, which is usually a carriage return code ($8D), or until a specified number of 
characters have been received. On exit, it returns the number ol characters received, 
Here is how to call ReadLine: 
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PHA ; space for result 

PushPtr InputBuffer ^pointer to input buffer 

PushWord MaxCaunt *,5ize of buffer 

PushWord #S8D ^EDL character 

PushWord EchoFlag ;1 = echo, = don't echo 

_ReadlL i ne 

PLA ;Pop character count 

InputBuffer is the area of memory in which the incoming characters are stored. 
MaxCount is the maximum line length, which must be less than the buffer size 

The last character reading function is TextReadBloek, With it, you can read m a 
group of characters and place them at a specified location inside a text buffer: 

PushPtr TextArea -.Pointer to start of text area 

PushWord Dffset jOffaet to start of input block 

PushWord Count ; Number of characters to read 

PushWord EchoFlag ', 1 = echo, - don't echo 
_TextReadBlock 

The problem with using TcxtReadBlock is that it does not exit until it receives 
Count characters. ReadLine, on the other hand, always exits when it receives the 
EOL character. 

KEYBOARD INPUT 

One function the Text Tool Set cannot perform is to check whether or not a key has 
been entered from the keyboard. You will want to do fliis, for example, if you design 
a program loop which is to continue looping until the user presses a key. You cannot 
use ReadChar because it waits until a key has been pressed before returning control 
to the application. One solution is to access the keyboard I/O locations directly, ill 
the Event Manager is active, you can keep looping until GetNextEvent or Task- 
Master indicates that a key-down event occurred.) 
The two main keyboard I/O locations are as follows: 

• $EOCO0O keyboard strobe (bit 7) + data 

• SE0C01O clear keyboard strobe 

When you are accessing these locations (or any other I/O locations for that matter), 
the m status flag must be set to 1 so that read or write operations affect the one- 
byte I/O location only. This is very important. 

To determine whether or not a key has been pressed, check the high-order hit 
of ' $EQC00O (the keyboard strobe hit). If it is 1, a key has been pressed and the 
lower seven bits of $EOC00O contain the key's ASCII character code. To clear the 
keyboard strobe so that the next read of SEOCOOO will not return the same keycode, 
access the &E0C01Q I/O location. 
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Here is a short subroutine you could call to check the .status oi the keyboard: 

ChecleKbd SEP #$20 ;8-bit accumulator 

LONGA OFF 

LDA $E0CQQ0 ;Checb keyboard 

BPL KbdExit ;Branch if nothing there 

STA IE0C01O -.Clear strobe 

KbdExit REP #$20 ;16-bit accumulator 

LONGA ON 
RTS 

Ha key has been pressed, the negative flag is set to ] and the character code is 
returned in the accumulator If no key has been pressed, the negative Hag is cleared 
toO. 

You must be careful while accessing keyboard I/O locations when keyboard 
interrupts are enabled, because all keypresses will be processed by an interrupt 
handler before you have a chance to read $EOCOOO to determine whether or not a 
key has been pressed, (Remember, keyboard interrupts are automatically enabled 
if the Event Manager is in use.) This is a particularly important consideration when 
developing desk accessories because they may be activated at any time from any 
application. 

You can check whether keyboard interrupts are enabled by calling the Cet- 
IKQ Enable function, in the Miscellaneous tool set: 

PHA ;space for result 

_GetIRQEnable 

PLA ;Get status word 

If keyboard interrupts are enabled, bit 7 of the status word result will be set to 1, 
When interrupts are enabled, you must first disable keyboard interrupts with 
IntSource, another function in the Miscellaneous tool set, Here is how to disable 
them: 

PushWord #1 ;1 - disable keyboard interrupts 

_ I nt Source 

Later in the program you can re-enable keyboard interrupts by passing a $00 
parameter to IntSource, but only do this if interrupts were enabled in the first 
place. 



442 Using the Text Tool S,l 



VIDEO OUTPUT 

Applications using the 80-column text screen cannot take advantage oi tool sets like 
the Window Manager, Menu Manager, and Dialog Manager because these tool .sets 
work with the super high-resolution screen only. Thus, you have to do a lot more 
work if you wish to follow desktop interface guidelines. Nevertheless, text-based 
applications are popular alternatives to similar graphics-based ones, because screen 
operations such as scrolling and updating take place more quickly. 

The drivers for most intelligent output devices support sets of commands you 
can use to control the way the devices handle subsequent characters. In most cases. 
a command is either a control character (a character with an ASCII code trorn to 
31} or a control character followed by a series of characters in a certain order. 

The driver for the SO-colturm column text screen has commands that (with one 
exception) are single control characters. You can use these commands to perform 
such useful actions as screen clearing; moving the cursor position up, down, left, or 
right; or highlighting subsequent characters. The commands supported by the 
BASIC and Pascal drivers for the 80-column text screen are summarized in table 
12-1. 

Notice that the ASCII codes given in table 12-1 have the high bit set because 
the 80-column video driver expects characters in this format. If the output OR mask 
is $80 {tlie usual case), you can also send codes with the high bit off 

Also notice that for the Pascal driver, the CR (carriage return) code does not 
move the cursor to the next line as it does when the BASIC driver is being used. 
You must follow the CR with LF (line feed) to move the cursor down one line. 

Character Display 

Table 12-2 shows which characters appear on the text screen when you send ASCII 
codes from $A0 to $FF to the 80-column video driver. These characters are usually 
displayed in normal video (white characters on a black background) but this mode 
can be inverted by sending a $8F (INVERSE) code to the driver first. To return to 
normal video, send a S8E (NORMAL) code. 

MetiseText 

Mouse-Text is a group of thirty- two icons representing such objects as apples, arrows, 
checkmarks, a file folder, scroll bar arrows, and shading patterns. You can use them 
to add a little spice to your screen displays. 

Each MouscTcxt icon corresponds to a standard keyboard character, as shown in 
table 12-2. To display a MouseText character, first enable the driver's handling of 
MouseText by sending a S9B code (MTXT.ON) and turn on inverse video by sending 
a SSF code (INVERSE), Then send the code for the character corresponding to the 
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Table 12-1: Control Commands Supported by the 80-Column Screen Driver 



ASCII 
Code 



Symbolic 

Name 



Actum 



$85 


CURSOBOFF 


$86 


CURSORON 


$87 


BEEP 


$88 


BACKSPACE 


$HA 


LF 


$8B 


CLREOP 


$8C 


CLRSCREEN 


$8D 


CR 



$8E 


NORMAL 


$8F 


INVERSE 


$91 


SET.40COL 


$92 


SET_80C:OL 


$93 


PAUSE 


S95 


FIRM.GFF 


$96 


SCROLLD 


S97 


SCROLLU 


$98 


MTXT_OFF 


$99 


HOME 


S9A 


CLRL1NE 


$9B 


MTXT.ON 



Do not display a cursor 

Display a cursor 

Sound a tone; volume, pitch set by Control Panel 

Move the cursor left one position 

Line feed; move the cursor down one line 

Clear the screen from the current cursor position to 
the end of the screen 

Clear the screen; move the cursor to the top left- 
hand corner 

Carriage return; for BASIC, move the cursor to the 
left side of the next line; for Pascal, move the 
cursor to the left side of the current line (follow CR 
with LF to move the cursor down one line) 

Enable the normal mode for text display 

Enable the inverse mode for text display 

Enable the 40-column screen display 

Enable the 80-columu screen display 

Stop receiving characters until a key is pressed 

Turn off the SO-column display and firmware 

Scroll the display down one line: leave the cursor at 

the same position 

Scroll the display up one line; leave the cursor at 
the same position 

Show inverse upper-ease characters instead of 
MouseText characters 

Move the cursor to the home position (the 
top left-hand corner of the screen) 

Clear the entire line on which the CUTS 
positioned 

Show MouseTcst characters instead of inverse 

u p p er-case characters 
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Table 12-1: Continued 

ASCII Symbolic 

Code Name 



S9C MGVERICHT 



$9D CI.REOL 



$9E SET.CURS 



$9E GOTOXY 



S9F MOVE UP 



Action 



Move the cursor one position to the right, moving 
the next line if necessary 

Clear the screen from the current cursor position to 
the end of the line 

For the BASIC driver only; Change the cursor 
character to the character which follows 

Far the Pascal driver only: Move the cursor to the 
position indicated by the two bytes that lollow; the 
first byte is the horizontal position plus 32; the 
second is the vertical position pins 32 

Move the cursor up one line (in the same column); 
do not move if the cursor is in the top line 



MouseText icon. Code SCI (A), for example, represents the Open-Apple icon. If 
you want the driver to display inverse characters instead of icons, send code $98 
(MTXT_OFF) to disable the conversion to MouseText icons. 

These are the MouseText symbols and their corresponding characters {they cor- 
respond to the codes from SCO to $DF): 



MouseText- 
normal — 



MouseText- 
normal 



^bklxklatei=iH.j^i^rPTiT^ 



-»£ABCDEFGHI JKLMNO 



l±-|4il+:MU-> 



gma i 



)PQRSTUVVXYZ[\] ' _ 



Cursors 

A cursor marks the position on the screen at which the next displayable character 
you send to the video driver will appear. It is normally a solid white box, formed 
by displaying an inverse space character. 

If you arc using the BASIC video driven you can change the cursor to any other 
character by sending a $9E (SET_CURS) command to the video driver, followed by 
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Table 12-2: Sj mbols lor (he Displayabfc ASCII Character Codes 



ASCII 




ASCII 




ASCII 




Code 


Symbol 


Code 


Symbol 


Code 


'■■<;i)tbol 


SAO 


[ space] 


SCO 


<§ 


|E0 


± 


$A1 


! 


$C1 


A 


%E1 


.1 


$A2 


•i 


9CS 


B 


SE2 


b 


$A3 


# 


$C3 


C 


$E3 


c 


$A4 


$ 


|C4 


D 


$E4 


d 


$A5 


% 


$C5 


E 


$E5 


e 


SA6 


& 


$C6 


F 


$E6 


r 


$A7 


• 


8C7 


G 


SET 


g 


$A8 


< 


$C8 


H 


$E8 


1, 


$A9 


) 


8CS 


I 


$E9 


i 


IAA 


* 


$CA 


J 


$EA 


i 


$AB 


+ 


$CB 


K 


*EB 


k 


$AC 


• 


$cc 


L 


•EC 


! 


$AD 


- 


$CD 


M 


$ED 


ni 


$AE 


■ 


$CE 


N 


$EE 


ii 


$AF 


/ 


SCF 


O 


$EF 


o 


$B0 





$D0 


P 


$F0 


P 


$B1 


1 


$D1 


Q 


*Fl 


•l 


SB2 


2 


$D2 


R 


$F2 


r 


8B3 


3 


$D3 


S 


SF3 


s 


$B4 


4 


$D4 


T 


SF4 


t 


$BS 


5 


IDS 


U 


$F5 


LI 


$B6 


6 


$D6 


V 


|F6 


V 


$B7 


7 


SD7 


w 


SF7 


H 


$B8 


8 


$D8 


X 


fiVS 


R 
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Table 12-2: 


Con tin net 










ASCII 




ASCII 




ASCII 




Code 


Symbol 


Code 


Symbol 


Code 


Symbol 


$89 


9 


SD9 


Y 


$F9 


y 


$BA 


: 


$DA 


z 


$FA 


z 


$BB 


i 


$DB 


I 


$FB 


{ 


$BC 


< 


$DC 


\ 


$FC 


1 


$BD 


= 


$DD 


J 


SFD 


} 


$BE 


> 


$DE 


- 


$FE 


~ 


$BF 


? 


IDF 


- 


SI'T 


[rubout] 



the code For the new character. There are also commands for turning the cursor on 
and (iff: use S86 (CURSORON'i to turn it on, and $85 (CURSOROFF) to turn it off. 

If you are using the Pascal driver, you can position (he cursor by sending a $9E 
code (GOTOXY) followed by bytes representing the horizontal and vertical positions. 
These positions are offset from their actual positions by 32 so that position (2,4) is 
represented by (34, 361. for example 

The BASIC screen driver does not support a curior-positiomng command. To 
serve this purpose, you will have to call a subroutine like the one in listing 12-3. 
On entry to the subroutine, the horizontal position must be in X and the vertical 
position in V 

To understand how this subroutine works, consider that the CS BASK] 80-column 
video driver keeps track of the current cursor position in three locations in page 
zero and page five of bank $00: 

• CH ($24) horizontal cursor position (0 to 79) 

• OURCH ($57B) duplicate of horizontal cursor position 

• CV ($25) vertical cursor position (0 to 23) 

To change the cursor position, you must place the new horizontal position in both 
CM and OURCH and the new vertical position in CV. (The position is automatically 
updated as you send characters to the screen) There is a complication that arises 
when CV is changed, however. The BASIC driver continues to use the old CV value 
until the cursor actually moves to another line- To foree an immediate repositioning, 
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Table 12-3: The 80-CoIumn Text Screen Parameters for Windowing and Cursor 
Control 



Bank $00 
Address 


Symbolic 
Name 


$20 


WNDLFT 


§21 


WNDWDTH 


$22 


WNDTOP 


$23 


WNDBTM 


$24 


CH 


S25 


CV 


$57B 


OURCH 



Description 



Left column of window (0 to 79) 

Width of window (1 to 80) 

Top row of window (0 to 23) 

Bottom row of window plus one (1 to 24) 

Horizontal cursor position (0 to 79) 

Vertical cursor position (0 to 23) 

Horizontal cursor position (0 to 79) 



NOTE: WNDWDTH must noi exceed 80 minus the value of WNDLFT 



you must place the desired value minus 1 in CV and then send a carriage return 
code to the output device. This is exactly what the GOTOXY subroutine docs. 

The GOTOXY subroutine also shows how to force long addressing (by putting a 
> in front of the label for an address) so that you do not have to change the direct 
page before writing to CH or CV. It also temporarily switches to an S-bit accumulator 
so that when you store the accumulator, the next location in memory is not over- 
written. 

Window Dimensions 

The 80-cohimn BASIC video driver is normally able to display characters anywhere 
on the screen. You can, however, tell it to confine its operations to any rectangular 
window within the screen by redefining four window boundary- parameters located 
in page zero of bank S00, These parameters are described in table 12-3. 
The usual values for the parameters in table 12-3 are: 

WNDLFT (left edge is column 0) 

WNDWDTH 80 (screen width is 80 columns) 

WNDTOP (top line is line 0) 

WNDBTM 24 (bottom line + 1 is line 24) 
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As when changing CH or CV, yon must switch to an 8-bit accumulator before storing 
a number to any of the window parameter locations. 

One parameter you must handle carefully is WNDWDTH. Tt must not exceed 
the difference between 80 (the maximum window width) and WNDLFT (the left 
edge). Keep this in mind whenever you change WNDLFT. 

Note that the window dimensioning techniques do not work when the Pascal 
video driver ts being used. They only work for the BASIC driver. 

PRINTER OUTPUT 

Printer drivers also support a variety of commands, mostly for setting formatting 
parameters that affect the appearance of printer output but also for setting up the 
communications link with the printer. The major commands supported by the drivers 
for the built-in serial ports on the GS are summarized in table 12-4. (Driver com- 
mands more appropriate to modem interaction are not given in this table.) To use 
a command, you begin by sending a Control-T code (ASCII $09) to the driver- You 
can change this attention code to another control character with a Control-I Control- 
x sequence, where Xontrol-x" represents the new attention code. 

Default settings for most of the printer parameters can be set with the Printer 
Port command in the Control Panel desk accessory-. 

The drivers for the Cs's internal serial ports (which can also he used with moderns 
and other serial devices) are not as flexible as some found in many non-Apple printer 
interlaces. Such interlaces often support several commands that let you print the 
contents of the text or graphics screens in many different formats and sizes with a 
few simple commands. Without these commands, an application programmer must 
write his own routines. 

Keep in mind that the printer itself may support commands that the printer 
interface does not. For example, to enable special printing modes, such as boldfacing 
or underlining, normally you send commands directly to the printer (through the 
printer driver, of course). If the command conflicts with a driver command, you 
may have to first send a command to the driver that tells it to ignore control 
character interpretation; for the GS serial port, this is the Z command. If you do 
this, you can restore control character interpretation by calling the InitTextDev 
function. 

THE TEXT TOOL SET IN ACTION 

The program in listing 12-4 shows how to implement many of the techniques 
described in this chapter. In particular, it shows how to use the PRINT and 
PRINTLN macros, how to enable and display MouseText characters, how to position 
the screen cursor, and how to turn on the printer. 
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Table 12-4: Control Commands Supported by the Driver Fur the cs Serial 

Ports, For a Printer Port Commands Must Be Preceded by 
Character S89 (Control-I). 

Command 

String Action 

nB Set the serial baud rate. 

n=0 default n=8 1200 baud 

n=l 50 baud n=9 1800 baud 

n=^2 75 baud n=I0 2400 baud 

n=3 110 baud n=ll 3600 baud 

n=4 135 baud n =l2 4800 baud 

n = 5 150 baud n=I3 7200 baud 

n=6 300 baud n= 14 9600 baud 

n = 7 600 baud n= 15 19200 baud 



nD Set the number of data bits nrid stop bits. 

n=0 8 data + I stop n-4 8 data + 2 stop 
n = l 7 data + 1 stop n-5 7 data + 2 stop 
n -2 6 data + 1 stop n = 6 6 data + 2 stop 
n=3 5 data + ] stop n = 7 5 data + 2 stop 



nP Set the parity. 

n=0 no parity bit n = 2 no parity hit 
n=i odd parity n— 3 even parity 



nN Si t the line length to n. 



CE E nable (CE) or disable (CD) line formatting. When enabled, the 

CD cs inserts a carriage return at the end of a line (the length is set 

by the nN command). 



AE Enable (AE) or disable (AD) proper operation of the Applesoft 

AD BASIC TAB commands. When enabled, the line length is forced 

to the video screen width. 



450 Using the Text Tool Set 



Table 12-4: Continued 



Command 
String 

BE 

BD 



XE 
XD 



LE 
LD 



R 



Action 



Enable (BE) or disable (BD) the buffering of incoming and 
outgoing characters. The buffers are each 25048 bytes in size. 
Characters are sent from the output buffer in response to an 
interrupt indicating that the peripheral device is ready to receive 
a chara< ter 

Enable XI or disable (XD) the XON/XOFF software handshake 
protocol. When enabled, and the firmware receives an XOFF 
character (ASCII $93), characters are not transmitted until an 
XON character (ASCII $91) is received. Some printers use this 
technique for flow control. 

Enable (LE) or disable (LD) the sending of a line feed character 
(AS< :i[ sv\ after a carriage return character (ASCII $8D). 
Enable this feature if your printer seems to print everything on 
one line, disable it if the printer double-spaces all output. 

Reset the serial port. This restores the default parameter settings 
set in the Control Panel. 

Zap control character interpretation, After this command, the 
firmware Ignores character sequences which would normally be 
Interpreted as commands. 
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Table R12-1: The Major Functions in the Texl Tool Set ($0C) 





Function 


Stack 


Description oj 


Function Name 


\itmhvr 


Paraint ' 


Parameter 


ErrWriteBloek 


|1F 


TextPtr(L) 


Ptr to block of text 






Offset (W) 


Offset to first character 






Count W 


Number of characters 
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Function Same 


Function 
Number 


Stack 

Parameters 


Description of 
Parameter 


ErrWriteChar 


$19 


Char (W) 


ASCII character to 
write 


BrrWriteCString 


$21 


CStringPtr (L) 


Ptr to C-stylc text 

string 


ErrW rite Line 


SIB 


StringPtr (L) 


Ptr to text string 


ErrWrite String 


$1D 


StringPtr (L) 


Ptr to text siting 


GetErrorDevice 


$14 


result (W) 


Driver type code 






result (L) 


Output slot (or vector) 


CetErrCIobuls 


SOE 


result (W) 


Current error AND 
mask 






result (Wj 


Current error OR 
mask 


GetlnGlobals 


$0C 


result (W) 


Current input AND 
mask 






result (W) 


Current input OR 
mask 


Getlnput Device 


$12 


result (W) 


Device type code 






result {L) 


Output slot {or vector) 


GetOutGlobals 


$0D 


result (W) 


Current output AND 

mask 






result (W) 


Current output OR 
mask- 


GetOutput Device 


$13 


result (W) 


Driver type code 






result (L) 


Output slot (or vector) 


InitTextDev 


$15 


DeviceNum (W) 


Device number 


Read Char 


s22 


result (W) 


Inputted character 
code 






EehoFJag (W) 


1 = echo/0 = don't 
echo 
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Function 


Stack 


Description of 


Function Name 


Number 


Parameters 


Parameter 


Read Line 


S24 


result (W 


Character count 






BufferPtr (L) 


Ptr to input buffer 






MaxCount (W) 


Size of buffer 






EOLChar (W) 


End-of-line character 






EchoFlaeW 


1 = echo/0 = don't 
echo 


SetError Device 


si! 


DeviceType (W) 


Dm ei type code 


■ 




SlotOrAddr (L) 


Error output slot (or 
address) 


SetErrClobals 


SOB 


ANDMask (W) 


Error output AND 
mask 






ORMaskiW 


Error output OR mask 


SetlnGlobals 


soy 


ANDMask (W) 


Input AND mask 






ORMask <W) 


Input OR mask 


SctlnputDevice 


$0F 


DeviceType (VV) 


Device type code 






SlotOrAddr (L) 


Input slot (or address) 


SetOutGlobals 


$0A 


ANDMask (W) 


Output AND mask 






ORMask (W) 


Output OR mask- 


SetOut put Device 


$10 


DeviceType (W) 


Device type code 






SlotOrAddr (L) 


Output slot (or 
address) 


TextReadBlock 


S23 


BlockPtr (L) 


Ptr to start of text 
block 






Offset (W) 


Offset to starting 
position 






Count (W) 


Number of characters 
to read 






EchoFlag (W) 


1 = echo/0 = don't 
echo 
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Function Name 


Function 
Number 


Stack 

Parameters 


Description of 
Parameter 


Text Shut Down 


$03 


[no parameters] 




Text Start up 


302 


[no parameters] 




TextWriteBlock 


$1E 


TextPtr (L) 


Ptr to block of text 






Offset (W) 


Offset to first character 






Count (W) 


Number of characters 


WriteChar 


$18 


Char (W) 


ASCII character to 

write 


WriteCString 


|20 


CStringPtr (L) 


Ptr to C -style text 
string 


WriteLine 


SJ1A 


StringPtr (L) 


Ptr to text string 


WriteString 


$1C 


StringPtr (L) 


Ptr to text string 



Table RI2-2: The Text Tool Set Error Codes 



Error 
Code 



$OC01 

$oc:o2 

$0C03 
$0C04 

S0C05 



Description of Error Condition 



Illegal device type code. 

Illegal device number. 

Illegal operation. 

Undefined hardware error, 

The device is no longer oil- 
line. 



Table R12-3; Useful Functions in the Miscellaneous Tool Set ($03) 



Function Same 



GctlRQEnahle 
IntSource 



Function 

S umber 



429 
S23 



Stack 
Parameters 



result (WJ 

In (Control (VV) 



Description of 
Parameter 



Interrupt status word 
Interrupt control word 
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Listing 12-1: Character Device Initialization Subroutines 



i Enable the 80-column video display far output and the 
•, 80-column keyboard input subroutine. 

VIDED^QN START 

PEA o -.BASIC device driver 

PushLong 03 ;Select slot #3 for output 

_5et0utpu t Device 

PEA 1 ; Initialize output device 

_lni tTextDev 

PEA -,BAS!C-type device 

PushLong #3 jSelect slot *3 for input 

_Set 1 nputDevice 

p^A ^Initialize input device 

_Ini tTextDev 

PEA $FF ;AND mask: do nothing 

PEA *8Q 'OR mask: set high bit 

_5et0utGlobala 

PEA *FF ;AHD mask: do nothing 

PEA $80 '.OR mask: set high bit 

_Set I nGloba Is 

RTS 

END 

t Enable the printer in slot 1. This is equivalent 
; to a PR#1 in the good old days. 

PRINT.DN START 

PEA ;BASlC device driver 

PushLong #1 ;Select slot #1 for output 

_Se tOutputDevice 

PEA 1 -.Initialize the output device 

_InitTextDev 

RTS 

END 
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Listing 12-2: The PRINT and PRINTLN Macros for Sending Text to the Active 
Output Device 



i PRINT 'text phrase' 

; This prints a line of text without a trailing CR, 



;Push pointer (high) 
i Push pointer ( I ow ) 
; W p 1 1 e String function 
;Too] entry point 



;Length of text 
iThe text itself 





MACRO 




*lab 


PRINT 


itext 


Slab 


PEA 


t isyscntl- 16 




PEA 


t ftsyscnt 




LDX 


#$1C0C 




JSL 


$E1 0000 




BRA 


elsyBC n t 


tisyscnt 


DC 


11 <L:Atext * 




DC 


C'Atext" 


elsyscnt 


ANDP 
MEND 





; PRINTLN 'text phrase' 
» 

■> This prints a line of text followed by a CR. 

MACRO 
Slab PRINTLN itext 

ilab PEA t*sy5cntl-16 -.Push pointer (high) 

PEA Usyscnt ;Push pointer (Idw) 

LDX #$1A0C ;WnteLine function 

JSL SE100Q0 ;Tool entry point 

BRA etsyscnt 

Usyscnt DC I1'L:Stext' -.Length of text 

DC C'itext" ;The text itself 

eAsyscnt ANOP 
MEND 

Listing l£-3: The COTOXY Subroutine for the 80-column Text St 



; GDTQXY Subroutine. Enter with the horizontal position in X 

'» and the vertical position m V. 

; Cursor hor i ?on ta 1 
; Cursor vertical 
;Cursor horizontal 
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CH 


GEQU 


$24 


cv 


GEQU 


$25 


OURCH 


GEQU 


$57B 



CR 


GEQU 


$8D 


GQTOXY 


START 
PHX 

DEY 

TYA 






SEP 


#$20 




LONGA 


OFF 



; Carriage return code 



;Save horizontal position 

; Reduce vertical coordinate by 1 
; and put it in the A register. 

;8-bit accumulator 



STA 



>CV 



REP 


M20 


LONGA 


ON 


PEA 


CR 


Wr i le 


:Char 



PLA 



SEP 


#$20 


LQNGA 


OFF 


STA 


»CH 


STA 


>OURCH 


REP 


**20 


LDNGA 


ON 


RTS 




END 





".Monitor's CV (cursor vertical) 
■.Back to 16-bit accumulator 

*, (do this first to make sure 

; the vertical change takes hold) 

;Get horizontal position 

; 8 -bit accumulator 



; Monitor's CH {cursor horizontal 
;CH for 80-column firmware 

; Back to 16-bit accumulator 



Listing 12-4; A Program for Exercising the Text Tools 
* Exploring the Text Tools * 



LIST 


DFF 


SYMBOL 


OFF 


ABSADDR 


OH 


iNSTIME 


DN 


GEN 


DN 


KEEP 


TEXT 


MCOPY 


TEXT. MA 



-.Object code file 
; Macro file 



MyCode START 
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;Moni tor 


zero page 


local l oris : 


WNDLFT 


GEQU 


$20 ; 


WNDWDTH 


GEQU 


$21 ; 


UINDTQP 


GEQU 


$22 ; 


WNDBTM 


GEOU 


$23 y 


CH 


GEQU 


$24 s 


cv 


GEQU 


$25 ; 


OURCH 


GEQU 


$57B ; 



Left edge of window 



Width: must be <■ 
Top 1 i ne 
Bottom line * 1 
Cursor horizontal 
Cursor vertical 
Cursor horizontal 



80-WNDLFT 



;Special video commands: 



CURSQRDFF 


GEQU 


$95 


CURSDRON 


GEQU 


$86 


BEEP 


GEQU 


$87 


BACKSPACE 


GEQU 


$88 


LF 


GEQU 


$8A 


CLREDP 


GEQU 


$8B 


CLRSCREEN 


GEQU 


$8C 


CR 


&EQL 


$8D 


NORMAL 


GEQU 


$8E 


INVERSE 


GEQU 


$8F 


SET_40CQL 


GEQU 


$91 


SET_80COL 


GEQU 


$92 


PAUSE 


GEQU 


$93 


F1RM_DFF 


GEQU 


$95 


SCRDLLD 


GEQU 


5 96. 


SCRDLLU 


GEQU 


$97 


MTXT.QFF 


GEQU 


$98 


HOME 


GEQU 


$99 


CLRLIHE 


GEQU 


$9A 


P1TXT_QN 


GEQU 


$9B 


MDVERIGHT 


GEQU 


$9C 


CLREOL 


GEQU 


$9D 


SET.CURS 


GEQU 


$9E 


MQVEUP 


GEQU 

PHK 

PLB 


$9F 




_TLStar 


tup 




_MTStar 


t up 




PHA 






_MMStar 


t up 




PLA 






STA 


My ID 



Cursor off 

Cursor on 

Beep the speaker 

Move cursor left 

Move cursor down 

Clear to end of screen 

Clear the entire screen 

Carriage return 

Normal video 

Inverse video 

Switch to 40-column display 

Switch to 80-column display 

Stop output until key pressed 

Turn off enhanced video firmware 

Scroll down 

Sc rol 1 up 

MouseText off 

Move cursor to top left corner 

Clear line 

MouseText on 
Move cursor right 
Clear to end of line 
Set cursor (BASIC only) 
Move cursor up 

Set data bank ■ program bank so we 
can use absolute addressing. 

Tool locator 
Miscellaneous Tools 



'.Memory Manager 



_Tex tStartup 
JSR VIDEDON 



;Text Tools 

;Set up 80-column I/D 
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; Just for fun, let's display the entire 
; MouseText character set: 

PRINTLH 'Here is the MouseText character set;' 
PEA CR 
_Wr i teChar 

PEA MTXT_DN 

JdriteChar -.Enable MouseText 

PEA INVERSE 

^UnteChar -.Select inverse mode 

LDA **C0 ; First MouseText character 

Showlcon PHA 
PHA 

_WriteChar ;Display it 

PLA 

INC A 

CMP *»EQ ;At the end? 

BNE Showlcon *,No, so branch 

PEA NORMAL 

_UriteChar ;Select normal mode 

PEA MT)CT_OFF 
WriteChar -^Disable MouseText 

PEA CR 

_WriteChar 

PEA CR 
Wr 1 teChar 

; GDTOXY positions the cursor: 

LDX *10 ^Horizontal position 

LDY *8 ^Vertical position 

JSR GQTOXY 
FH31NTLN '<--- coordinate (10,8)' 

Get.Mode PEA CR 
_WriteChar 
PEA BEEP 
_Wn teChar 
PRINT 'Send output to [Slcreen or [Plrinter? ■ 

PHA 

PEA 1 ;echo the input 

_ReadChar ;Read keyboard input 

PLA 
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CMP 


#'S' 




BEQ 


ShowMsq 




CMP 


1 s 1 




BEQ 


ShowMsg 




CMP 


#ipi 




BEQ 


Pr intMsg 




CMP 


#ipi 




BNE 


Get^Made 


PnntMsg 


JSR 


PRJNT_0N 


ShowMsg 


PEA 


CR 




Jirl 


teChar 




PEA 


CR 




JJri 


teChar 



; Enable the printer 



PR1NTLN 'PRiNTLN 15 a macro which displays a line' 
PRINTLN 'of text followed by a Carriage Return.' 

PRINT 'PRINT does the same thing, except there' 

PEA CR 

_Wr 1 teChar 

PRINT '15 no trailing Carriage Return." 

PEA CR 

_WriteChar 

PEA CR 
_Wr 1 teChar 

PRINT 'Preas any key to Quit: « 

PHA 

PEA tOOOO ;No echo 

_ReadChar ; Wa 1 1 for keypress 

PLA 

JSR VIDED_DN ;Back to 80-column screen 
;Shut down the tool sets we used: 

^TextShutDown 

PushWord MylD 
_MMShu tDown 

_MTShu tDown 
_TLShij tDown 

_QU1T QuitParms 

BRK *P0 ; (should never get here) 
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Quit Parma DC I 4 • D ' 

DC I 2 ' $00 00 • ;Not restartahle 

My ID DS 2 

END 



Use the COPY directive to include the PRINT^ON and 
V1DE0_DN subroutines found in listing 12-1 and 
the GOTDXY subroutine in listing 12-3. 
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APPENDIX 1 



ASCII Character 
Codes 



Characters such as letters and digits are stored inside the c;s in binary form (a series 
of Is and Osh the only form a computer understands. The c;s system software uses 
the ASCII (American Standard Code for Information Interchange) scheme for as- 
signing characters and symbols to numeric codes. In fact, almost all microcomputer 
software uses the ASCII standard. 

In the ASCII standard, each character is represented by a series of seven Is and 
Os. These binary digits occupy the first seven bits of the byte in which a character 
is stored. This means that 128 unique codes are available, enough to account for all 
the printable symbols on a standard typewriter keyboard and a few more. The 
unused bit in a byte is usually set to 0, but if you are sending characters to the text 
screen of the c;s T it must be set to 1 (see chapter 12). 

The system font, which QuickDraw li uses when it draws text on the super high- 
resolution graphics screen, assigns special symbols to the 128 codes which have the 
high bit set to 1. These symbols are not defined by the ASCI] standard and can 
represent any symbol the designer of the font wishes. 

The first 32 ASCII characters are called contra! characters. They are not supposed 
to represent visible symbols; instead, they arc to be sent to a video display, device 
or a printer controller to cause it to perform some special action such as ringing a 
bell (ASCII code 7, belli, moving the cursor or print head to the beginning of a line 
(ASCII code 13, carriage return), or moving the cursor or print head down one line 
(ASCII code 10, linefeed i. 

Although the driver for the CS .80-column texl son en reacts to most control 
characters in standard ways see chapter 12), the QuickDraw II text-drawing func- 
tions do not (see chapter 6}. Instead, QuickDraw attempts to draw a symbol that 
was assigned to the code when the font was defined. For the system font, four 
control characters are associated with special symbols: 
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$11 Open-Apple icon 

$12 Checkmark icon 

$13 Diamond icon 

$14 Solid- Apple icon 

Other control characters in the system font are blanks or are undefined. (Undefined 
characters appear as white question marks on a black background.) 

The following table shows the standard symbols for all 128 ASCII character codes. 
It also indicates how you can enter each character code from the keyboard. 

Note that in certain situations, the OS displays MouseTcxt icons on the text screen 
instead of the standard symbols for codes $40 to $5F. Sec chapter 12 for an expla- 
nation of when it does this. 



Table of ASCII Character Codes 



ASCII code 


Symbol (or mnemonic) 




Dec 


Hex 


Keys to press 


000 


$00 


NUL (Null) 


Control (a 


001 


$01 


SOH (Start ofheadei 


Control A 


002 


$02 


STX (Start of text) 


Control B 


003 


$03 


ETX {End of text) 


Control C 


004 


$04 


EOT (End of transmission) 


Control D 


005 


$05 


ENQ (Enquiry) 


Control E 


006 


$06 


ACK (Acknowledge) 


Control F 


007 


$07 


BEL (Bell) 


Control G 


008 


$08 


BS (Backspace) 


Control H or 
Left-arrow 


009 


$09 


1IT (Horizontal tabulation) 


Control 1 or 
Tab 


010 


S0A 


LF (Line feed) 


Control J or 

Down -arrow' 


011 


$0B 


VT (Vertical tabulation) 


Control K or 
Up-arrow 


012 


SOC 


FF (Form feed: 


Control L 
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ASCII code 


Symbol (or mnemonic! 


Keys to press 


Dec 


Hex 

SOD 


013 


CR (Carriage return) 


Control M or 
Return 


014 


80E 


SO (Shift out) 


Control N 


015 


SOF 


SI (Shift In) 


Control O 


016 


S10 


DLE (Data link escape) 


Control P 


017 


$11 


DC] (Device control 1) 


Control Q 


018 


$12 


DC2 (Device control 2) 


Control R 


019 


$13 


DCS (Device control 3) 


Control S 


020 


$14 


DC4 (Device control 4) 


Control T 


021 


Slo 


NAK (Negative acknowledge] 


Control U or 

Right-arrow 


022 


$16 


SYN (Synchronous idle) 


Control V 


023 


$17 


ETB (End transmission block) 


Control W 


024 


118 


CAN (Cancel) 


Control X 


025 


$19 


EM (End of medium) 


Control Y 


026 


$1A 


SUB (Substitute) 


Control Z 


027 


$1B 


ESC (Escape) 


Control [ or 
Ese 


028 


SIC 


FS (Field separator) 


Control \ 


029 


$ID 


GS (Group separator) 


Control ] 


030 


$1E 


RS (Record separator) 


Control * 


031 


S1F 


US (Unit separator) 


Control _ 


032 


$20 


(space) 


Space Bar 


033 


S21 


! 


Shift 1 


034 


$22 


•' 


Shift ' 


035 


$23 


# 


Shift 3 


036 


$24 


$ 


Shift 4 
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ASCII code 


Symbol (or mnemonic) 




Dec 


Hex 


Keys to press 


037 


S25 


% 


Shift 5 


038 


S26 


& 


Shift 7 


039 


$27 


• 


• 


040 


$28 


( 


Shift 9 


041 


$29 


1 


Shift 


042 


$2A 


* 


Shift 8 


043 


$2B 


+ 


Shift = 


044 


S2C 


i 


■ 


045 


S2D 






046 


$2E 


. 


. 


047 


$2F 


/ 


/ 


048 


$30 








049 


$31 


1 


1 


0.50 


$32 


2 


2 


051 


$33 


3 


3 


052 


$34 


1 


4 


053 


$35 


5 


5 


054 


$36 


6 


6 


055 


$37 


7 


7 


056 


$3fl 


s 


H 


057 


139 


9 


9 


058 


$3A 


: 


Shift ; 


059 


$3B 


- 


; 


060 


$3C 


< 


Shift , 


061 


$3D 


= 


= 


062 


$3E 


> 


Shift . 
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ASCII 


code 




Dec 


Ilex 


Symbol (or mnemor 


063 


$3F 


? 


064 


$40 


i 


065 


$41 


A 


066 


S42 


B 


067 


$43 


C 


068 


$44 


D 


069 


$45 


r 


070 


$46 


v 


071 


$47 


G 


072 


148 


11 


073 


$49 


1 


074 


|4A 


1 


075 


$4B 


K 


076 


S4<: 


t. 


077 


S4D 


M 


078 


$4E 


\ ; 


079 


$4F 





080 


$50 


V 


081 


$51 


Q 


082 


$52 


R 




$53 


s 


084 


$54 


T 


085 


$55 


U 


086 




V 


087 


$57 


w 


088 


$58 


\ 



Keys to press 


Shift / 


Shifi 2 


Shift A 


Shift B 


Shift c 


Shift D 


Shift E 


Shift F 


Shift c; 


Shift H 


Shift 1 


Shift J 


Shift K 


Shift L 


Shift M 


Shift N 


Shift 


Shift P 


Shift Q 


Shift H 


Shift S 


Shift T 


Shift U 


Shift V 


Shift W 


Shift X 
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ASCII rode 



5f£ 1{rx Sy mbol (or mnemonic) Keys to press 



089 


$59 


\ 


090 


85 A 


7 


091 


$5B 


1 


092 


$5C 


\ 


093 


S5D 


1 


094 


S5E 


- 


095 


S5F 




096 


$60 


- 


097 


Sl,| 


a 


098 


$62 


b 


099 


$63 


r 


100 


$64 


d 


101 


$65 


e 


102 


$66 


1 


103 


$67 


g 


104 


S6.S 


h 


105 


$69 


i 


106 


$6A 


J 


107 


S6B 


k 


108 


$6C 


I 


109 


$6D 


in 


110 


$6E 


n 


in 


$6F 


o 


112 


$70 


p 


L13 


S71 


1 


114 


$72 


r 



Shift Y 

Shift Z 
I 

1 
Shift 6 

Shift - 

A 
B 
(: 
I) 
E 
F 
G 
II 
1 

I 
K 

L 

M 

N 


P 
Q 

H 
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ASCII 


code 


Symbol (or mnemonic) 


Keys to press 


Dec- 


Ilex 


US 


$73 


s 


S 


116 


$74 


l 


T 


117 


875 


I! 


U 


118 


$76 


V' 


V 


119 


$77 


W 


w 


120 


87S 


X 


X 


121 


$79 


> 


Y 


122 


S7A 


z 


/ 


123 


87 U 


! 


Shift [ 


124 


87( . 


1 


Shift \ 


125 


87 D 


\ 


Shift ] 


126 


$7E 


~ 


Shift ' 


127 


S7I- 


(n j bout) 


Delete 
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CMOS WS5C816 and W65C802 
16-Bit Microprocessor Family 



Features 

• Advanced CMOS design 'q» low power consumption and increased 

noiWP immyniiy 

» Single 3-6Vuowei supply. 5V specified 

■ Emulation mode allows complete herawnre and software 
compel in ily n Eh BOOS ilei pjrn 

■ 24-oir address bus allows access 10 1 6 MBytes o-i memory space 

■ Full 16-bit ALU. Accumulator Slack Pointer, and inde« Hsgi iters 

■ Valid Daia Address I VDA,i and valid Program Address i VPA|i output 
allows dual cacne ana cycle steal DMA i mplemeniabewi 

■ Vector Pull (VP) oulpul indicate* wfien interrupt vectors are bmng 

addressed May be u&ed io implement veciorvd «nf.errijpt design 

• Abort (ABORT) inpul and assooftled vector supports virtual memory 
syetern design 

■ Separate program and data sank rvglstari allow program 
segmentation a* lull 15-MByte linear addressing 

■ NewDi reel Register »nd (tact relative addressing provides capability 
fo* le-enirani re-cursive and relocatable programming 

• 24 addressing modes — 13 original 6502 modes, plus 11 new 
addressing modes with 9< msvuelions using 255 opcodes, 

• New Wail lor Inlerrupl (WAIf and Stop the Clock <STP| in*iru£tit>n» 
'ul r -ei reduce powe* consumption, decrease interrupt latency and 
allows SynCfl id.- \t ail cm with (ilernal events 

■ New Cp- Processor miirvrtKjn. <COP> with associated vector sup- 
ports co-processor configurations. • e floating pomi processors 

• New block move acii 1 1 



Genef el Description 

WVDC'i VVeoCaOS and WftSCaie are CMOS 16-bit microprocessors lea- 
tunnglotal software compatibility with their B-DH NMOS and CMOS 6500- 
seoes predecessors The W65Ca02 is pm-io-pin compatible with a-bil 
devices cu rrenlly available wmte the WS5CB16 emends addressing lo a 
lull 16 megabytes These devices -alter ire many advantages ol CMOS 
technology. Including increased noise immunity, higher ratability, and 
graaily reduced power requirements A software switch determines 
wneiner tne processor is in ire 6-Ut emulation " moos or in me native 
mode, inus allowing eittting systems io use tne expanded reaiures 
Aa shown in the processor prc-gramming mode*. 1na Accumulator ALU, 
X and) V Index registers and Slack Pointer register have alt been ex- 
tended Id 16 bits. A new 16-bil Direct Page register augments the Direct 
Page addressing mode flormeriy Zero Page addressing! Separata 
Program Bank and Data Ban* registers allow 24-blt memory addressing 
with segmented or linear addressing 
Four new signals provide the system designer with many options The 

A8QP.T input can inlerrupl Ihe currently e«ecu1»ngi instruction wilUgul 

modifying internal register, thus allowing virtual memory system design 
Valid Data Address (VDAp ana Vend Program Address (VPA) outputs 
facilitate dual cache memory by indicating whether a date segment or 
program segment is accessed Modifying a vector is made easy by 
monitoring the Vector Pull IVP) uutout 

Note To assist the design engines', a Caveat Bno Application Intor- 
maiicxt section has been included wfrwi this datasheet 



K Register Hi 

i.Xh; 



X Register Low 



W55C816 Processor Programme nig Mod*! 
! l¥if&~~ | i eat ; i bits 

' Dai a Bs r v ''"i 
__(DBHI_ " 

fOato Bank Heu 
J [DOOl 

I 

I 00 

Regnlers 



Y Regsttn Hi 
<YH) 



VI 



V Register low 



Slack flMiStcr HiX 
lSH| <*> 



:sl 






A::.-:nti.„i,Mo' 

<B1 



|CJ 



AocuNsuHor 



■rogrami Hanii Beg 
<PBRi 



Piubbhi 

IPCHJ 



"H 1 — 
(PC) 



Counter 
"(PCL) 



L_ 



Direct Peg Hi ' Direct PJeg Low 



Status Regis U r Coding 



STATUS HEG :m 



JJR 



H V M :> D 



I C 



-tMijLAflON I -6302 

NATIVE 



LI— CAP.P.V 
ZERO 
IRQ DISABLE 
*— OEOMAL MODE 
^ INDEX REG SELECT 
L- MEMORY SELECT 
OVER FLOW 
•-NEGATIVE 



= TRUE 

- RESUIT ZERO 

= DISABLE 

= THUE 

-BBrTO- 18 BIT 

-sairo- 16 BIT 

= TRU€ 

• NEGATIVE 



Pin Configuration 



Vllf ■ f 1 1 s 1 1 



incr ' 

•-•- I 



Tsassaasas s 



; hi; | p;; 



1 1 1 s s i J ! ; * j 



•> =>w 

"• J Si 



Itlllllllll 



«4»T:= , 
age: • 

— —I ■ 

— - ■ 



For notes, rater to Packaging Information sertion 



w 3et«H 
ii a«n 



I THE WESTERN DESIGN CENTER. INC. 
H1 66 baat B^wn HciUci ■ iveu n-irnmf)5aj3«603 96345^5 



Advance loformnHon Date Sheet 
This is advanced intortnafion and 

specifications are subject to change 
without notice. 
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Absolute Maximum RiUngi: (No** i) 



Ming 


Symbol 


ValiM 


Supply Voltage 


Vdc 


-0 IV 10 *7 OV 


Input Vo'liga 


vm 


-0 3V lo Voo -0.3V 


Operating T«mp«f Slure 


i., 


ii' Ctc • fi.-C 


Storage Temperature 


Ts 


WClO-lWC 



This device contains input protection agairisl damage due to high stain 
■• oil ages or aleclnc 1«elds. however, precautions should betaken to avoid 
application o» voltages higher than the maaimum rating 

1 Exceeding these ratings may cause permanent damage. Functional 
operation under these conditions i* not impl»ed 



DC Chir»eterl*llet (All D*v1cti): vpo = 40V ±S%, Vs5 - OV ft 


0' Cto -TO'C 








Parameter 


Symbol 


MHI 


Mai 


Unit 


Input High Vqitaja 
RES RDV, IRQ, Data, SO, BE. 
02 (INK MMI, ABORT 


VIH 


20 

rj •' .... : 


VOD • 0.3 
Wno ■ 03 


V 

V 


Input Law Voltage 
RES. RDV, IRQ, Data. SO BE. 
02 HNr. MMI. ABORT 


VlL 


-0 3 
-0 3 


oe 

02 


V 
V 


'nnui Lea.-. ads Current | Vin - !o Vod) 

'.Ml. IRQ. SO. BE ABORT rlnlernal Pullup) 
RDV | internal Pullup OpenDrami 

_ 
Address Dara R.« i.GM Sra'e. BE 0: 


llN 


-100 

100 

1 

10 


1 
10 

1 
10 


*rA 

U A 

*A 


Output High Voltage t»o« ■ IQOWA) 
SYNC, Data. Address. Rw ML. VP. M/X E VIM vpa 
01 iouti #>2iauri 


VOH 


or vdo 




V 


Output lo* VoMaqe |Igl : 1 6mA| 

SYNC. Data Address WW ML VP M. X t VDA vPA 
«l |OUT| #2|OUT| 


. 




. i 


V 


Supply Current iNo Loadr 


Ion 




t 




Standby Current Into Load. Data Bus - VM or van 

i'L'J M,'i \wj 'jfj at ABOHr 0Z - vrp\ 


isa 




to 


*A 


Capactance (Vin = OV T* = 25" C, • = 2 MHi| 
Logic. 021 IN J _ 
Address, Data. R.vV lOir Suiei 


Cm 

c- 




i .' 
14 


pf 



Pin Function Tablt 



Pin 


Description 


AiJ Al' 


Address Bu* 


ABORT 


AfiOrt Irtpul 


BE 


Bus Enaeie 


02<l«r 


PnaseJ in Clock 


01 (OUTj 


Phase 1 Out Clock 


02 lOUTl 


Phase 2 Out Clock 


DO-D7 


Data Bus (G65SCoOZf 


D0.'BAO-D7'BAr 


Data Bus. Muilipie«ed IG6SSC8I6I 


E 


Emuialion Seiein 


IRQ 


Inlerrgpl R*quest 


vT 


Memory Loch. 


wn 


Mode Select (Pv ov Pi) 



Ma 


DeecrkpMon 


NC 


No Connection 




Non-Maskable Interrupl 


ROY 


Ready 


Res' 


Reset 


R/W 


Pv, v: ■-;■ , ,. 


50 


Set Overflow 


SYNC 


Synchronize 


VOA 
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Functional Description 

The IZV61C302 offers Ihe design engineer tne opportunity 10 ulilize Dotn 
existing software piogiams ar»d hardware configurations, wnue Also 
. i ho adOpdaavanlagasarincreased register lengmi and ■•Her 
execution time* The W65C802 s CH« o1 use deirgn ana impiemema- 
fion features provide Ihe designer witn increased iienbiiity and reduced 
implementation costs In ihe Emulation mode, 1(19 W6&C6Q2 not only 
oilers software compatibility Bui is siso hardware (pm-lo-pm) com 
pebble wnn 6502 designs plus n provides the advantage* t>l 16- bit 
inwrnai operation in 650y.eompai.ote application* Th* v\66CMl2 is an 
Bxcatieni direct replacement microprocessor fgr 8502 de*>gns 

Tne VV65CS1© provider ine design engineer w-th upward mpbiMv and 
soltware compatibility m applications where j 16-bit system conr,guifl- 
non 1* desired Tne w*SCet6's 16-bil hardware conliguration, coupled 
••'iis^'twam allows a wide selection ol system applications In 
trie Emulation mode (he W65C*16 oilers many advance* .nciudmg 
run software compatibility wiitt 8502 coding In addition the W6SCs<6s 
powerful inslruchon sol and addressing mods* make il an ekcellent 
choice lor new 16- bit designs 

Internal organization 0' Ihe W6SC802 and weSCfliS can be divided «nto 
iwoparia i) Th* Register Section, and 2) Tr»e Control Section Instruc- 
tions (or opcodes) obtained from program memory are executed try 
implementing a series at data transfers within mo Register Section 
Signals that cause flat* imnsfers to be eaecutod arq generated wilmn the 
Control Section Sow ihe W63C30Z and the W65C81© have a t5-on 
internal a 1, 1 toctuni wtfli an B-bat tuittrrial dala bta 

Instruction Register and Decode 

An opcode enters the processor 00 The Data 8u* and 1* latched into I he 
Instruction Register during vne insiruciion letch cycle This instruction 
is then decoded along wiinummoand interrupt signal*. logeneratethe 
various I nil ruction Register control signals 

Timing Conliol Unit (TC J J 

The Timing Control U mi keep* track of each instruction cycle as it is ex- 
ecuted The TCU is set to zero each lime a "1 <n*if uciianteich ise leculed, 
and is advanced at the beginning ol eact cycle lor as ma ny cycles as »> 
required to complete the instruction Each data transfer between regis- 
ters depends upon decoding theconienHofooli- ihe Irisiruclion Regis- 
ter ana tn* Timing Control Unit 

Arithmetic and Logic Unit (ALU) 

Ail ariihmeiic and logic operations take piece wiihm ine 16 bit ALU In 
addition to data operation?.. 1 ho AL U also caicu latcs ih« ellec* ve address 
lor relative and indexed addressing modes The rnsuH of a data operation 
•a stored m either memory or an internal register Carry, Negaiive Owrr 
How and Zero flags may be updated following the ALU data operation 
Jnieffial Regis ten [Rdfaa ib Pragrammmg Modeii 
Accumulators (A, B, CJ 

The Accumulator is a generaJ purpose register which stores one of Ihe 
operands, or th» resu'l 0* most arithmetic and logical operation* in in* 
Native mode |E^fl). when ine Accumulator Select Sit <M* equals zero 
Ihe Accumulator ■ established a* te Bits wide (A • B Q v, 
Accumuiaior Seiecl Bit (M| equals one. the Accumulate* n pita wide 
I A| In this case, the upper 6 tuts |B| may be used lor temporary storage 
m conjunction with the Exchange Accumulator <XBA) instruction 
Dale Bank Register (DBA) 

CHinng modes of operation, the S-bit Dal* Bank Register nolds the de- 
fault bank add < *u lor memory transfers The 24- pit address is composed 
of Ihe iQ-bii instruction effective address and the B-Dii Data Bank ad- 



dress The register value is muHipi*i»d with the data value and u preaeM 
on the Data 'Address I m** during the first hall of a data transfer memory 
cycle for the WSSC81« The Data Bank flag liter is initialized tozerodui- 
-., Heart 

Direct (D) 

The 16-bit Direct Register provide* an address offset lor all instruction* 
using direct addressing The effective bank zero address 1* lormed by 
adding the 3-bd inslruchon operand address lo the Direct Register Tl>e 
D-rect Register is initialized to zero during Henri 

Index (% and Y) 

There are two lnde» Regular* <X and Yj which may be used as general 
purpose registers or 10 provide an wdtr* value lor calculation ol the af- 
fective address Wnon enetutmgan instruction with indeaed addressing, 
the rtncroprcK-.rssor fetcnea lf»e opcode ana the case address, and then 
modifies the address by adding the index Register coment* to the ad- 
dress prior to performing the desired operation Pre-mdemng or posl- 
indenngof indirect addresses may be selected in the Native mode (ED). 
both Indei Registers are 16 txrj wide Crowding the Index Select Bii (X| 
equals iero) 11 the 1 nam Select Sri (X) equals one, both register* will be 
a bits w.de. anil |ha high byte is forced to zero 

Processor Status (P) 

Trw 8-tsit Processor statu* Register contams statu* flag* and mode select 
ens Tnecairy (CI Mega1<ve «N|, Overflow |W|. and Zero |Zl status nag* 
serveto report th* *tatusof most ALU oparaiions These status flags a r* 
tesledby useol Conditional Branch instructions The Decimal r|0 1, IRQ 
Disable (li, Memory/Aecumulater (M|, and Inde* |X) on* are used as 
mode select tiags Trww Hags are set by Ihe program tochange micro- 
processor operation* 

The Emulation |Ej seiecl end the Area*; |B| flag* are accessible only 
througn the Processor Status Register Trie Emulation mode select flag 
1* selected by ihe Exchange Cany and Emulation Bits (XCE) instruction 
~.r.- i rVSaCBGS and WOSCBie Mooa Comparison Wkattralai iha 
features of the Native I E=0) and Emulation lE-i) modes TneManox 
Hags are always equal to one in the Emulation mode Wnen an interrupi 
i"-i_uia during the Emulation mode the Break flag is written 10 stack 

1 > *> bit 4 of in* Processor Siatus Register 
Program Bank fteglstoi (PBH) 

Tne B-bit Program Bank Register holds the bank address lor an insiruc- 
iion fetches TheSa-CHladdressconsisnoftne 16-bil mstruciionieilective 
address and Hie ft-bit Program Bank address T ne register value ■* rrau'ti- 
pieted with in* data value ana presented on the Data; Address lines dunng 
ilie'nsi nailoi a program memory read cycle The Program Bank Regi*- 
ler 11 initialized lo zero during Reset The Phk instruction pushes the 
PBR register onto tne Stack 

Program Counter (PC) 

Tne 16-tMt Program Counter Regisler provides Ihe addresses which are 
used to step 1» microprocessor through sequential program instruc- 
tions Tne register is 1 ncrementedeach time an. nstrwehon or operand is 
fetched irom program memory 

Slack PoJnter (S) 

Tne Stack Pointer ■» a 16-bit register which 14 used to indicate I ho rve«t 
available location 1 n the stack memory area it serves as the eltecdve ad- 
* et* m slack addressing modes as well a* subroutine and interrupt pro 
ceasing The Stack Pointer allow* simple implementation ol nested sub- 
roulines and multiple-level interrupts During the Emuia1<on mode, the 
Stack Pointer high-order byte (SHI ■* always actual lo one The bank ad- 
dress lor all stack operation* i* Bank zero 
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Signal D*«rripUon 

The following Signal Description applies to both the WB5CB02 and it» 
W65C816 *M«pl as otherwise noted 

Abort (ABORT)— WS5C««6 

The Abort input is used to abort instructions lusuarly due to an Address 
Buscondllionl A negative tnnntlon will whibit modiliesuon M any In- 
ternal register during the cuf r*nt inwucoon. Upon completion oi thci 
liwtrucUon.ao Interrupt sequence is imtn»t*d The localion ol the aborted 
opcode is stored m ft>* relutn address 'n slack nrnmotf The Abort uwctoi 
address isOOFf F6.9 1 lEmuWiDft nrvodel or 00FFE8.9 I Mature mode) Hoi* 
that ABORT is a pulse-sensitive signal, i.e , a n abo rt will occur whanewir 
tnere is a negative puis* lo* level J on |h* ABORT pin d unng * *2 eloc* 

Address Bus (A0-A15) 

These S'nteen output lines form Ihe Address Bus lor memory aiid I/O 
eichangeon the Gala Bus When using the W65C816, ire address lines 
may base* to Ihe high impedance suite by the Qui Enable (BE.| stgrval 



Bus Enable (BE> -W65CB16 

me Bus Enable input signal allow* paternal control o1 itie Address and 
Data Butlers, a* won as me R'W s>gr*al With Bus Enable high, the H.W 
ana Address Buffers are active. The Dat* Address Butters are a<:t-ve 
during I he first hall ol »»ery cycle and the second hall ol a writ* cycle 
When BE is low these buffers •r»dl*abted Bus Enable is an asynctirtj- 
noui signal 

Data Bus (DO-07)— W65C802 

Trie eight Date Bus lines provide an b-brt bidirectional Data Bus lot use 
during ants enchange&brlwwrn the microprocessor and external mem- 
ory or peripherals Two memory cycles are required lor the transfer of 
16-bii values 

OBMJAddrau Bus {O0BA0-D^BA7>— W65C816 

Thme eight lines multiples address Pits BAO BA7 with the d»ia value The 
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address is present during the first hall ol a memory cycle, and the data 
val ue is read or wn Hen du n ng tne iecaifl half of the memory cycle two 
memory cy£l«*arer*quired to If ansfer 16-nii values These lines may be 
set lo the high impedance slate by the Bus Enable (BE) signal 

Emulation Status (£)— W85C«16 

The Emulation Status ou1:pulre1l*clair.o*tai*ol the Emulation (El mode 
ling in in* Processor Status (P| Register This signal may be ihoughi ol 
as an opcode extension and used for memory and system marmgemem 
Interrupt Request (IRQ) 

The interrupt Request inpul signal is used to request trial an interrupl 
sequence be initiated. When in* IRQ Disable III fag ia cleared, a low in- 
put logic level initiates an interrupt sequence ifler ir«» current instruc- 
tion is completed The Wait for interrupt < WAli iniiruct <ar. may be ex- 
ecuted to ensure in>v i nierruot wnir be recognued immediately Trie inter- 
rupt Requital vector ad dress is DOFf FCF iEmi.lationmaa#[orOOFFEE F 
(Native model Since IRQ is a level-sensitive input an interrupt win 
occur >f the interrupt source was not cleared since me last interrupt 
Also, no interrupt will occur II trie interrupt source is cleared prior to 
interrupt recognition 

Memory Lock (ML)— W65C816 

The Memory Lock ouipui may Be usM to aneure the integrity ol Read- 
Modily-Wnie instructions m a multiprocessor system Memory Loch 
indicates inn need to deter arbiimtion of the nenl bus cycle Memory 
Loch is law during tne urn tnrae or live cycles of ASL, DEC, INC LSR. 
ROL ftOR, TRB. and T58 memory referencing insirueligns. depending 
an the slate ol ine U Mug 

Memory (Index Select Suiua (M.'X) - W65CBTG 
This multiplexed ouipui reflects the stale ol trie Accumulator (M) and 
lnde» i'Xi select flags | bits 6 and * ol tne Pracimsoi Status IP) Register 
Hag M is valid during tne Pnas«2 clock negative transition and Flag X is 
valid during the Phase 2 cloth positive transition These bits may be 
inougni of as opcode extensions and may Da used lei memory and 
system management 

Non-Maskable Interrupt (NMI) 

A negative transition on ihe NMI input imti lies an interrupt sequence A 
nign-to-low transition initiates an interrupt sequence after the current 
instruction is completed The Wail for Interrupt (WAIJ instruction may be 
e«e*uie<] to ensure that the inierrup/l will be recog nized immedialaly The 
Non-Maskable Interrupt vector eddriaK m OOP FPA,B (Emulation mode) 
or QOFFEA.B (Native mode) Since NMl is an *dge-*en»itivr 
interrupl will occur i1 there is a negative transit ion w hile servicing apre- 
.'ious mteirupi Also, no interrupt mil c-c«wr II NMI remains low 

Phase I Out (*1 (OUT))— W6SC0O2 

This inverted clock output signal provides liming fat erne-mat read and 
write operations Enecutmg the Stop ISTPI inslructwn notd* inn clock 
■n the lovi si a to 

Phut 2 In (02 (IN)) 

This is tne system clock input to ine microprocessor internal clock gen- 
eral©! (equivalent Io#0("N) u-ntne6SCI2t During Ihe low power Siandby 
Mode, #2 I IN) should Da held In the nigh slate to preserve I he contents 
Ol ifiternfll registers. 

Phase 2 Qui («2 (OUT))— W65C802 

This clock ouipui signal provides timing tor external reed and write op- 
erations Addresses are valid (attar ine Address Setup Time (Tos]) fol- 
lowing Ihe negative transition ot Phase ? Qui Executing the Stop 1ST P| 
instruction holds Phase 2 Out in ine High Hate. 

Read/Write Ifl 'Wj 

When the WW output signal is in tne nigh state, tne microprocessor is 

'eadmg djta from ternary or I/O When in ine hi w state, ine Data Bus 

contains valid data Irorn the microprocessor which is to be stored al the 

addressed memoiy location When using me W&&C016. Ine P/vV signal 

may oe sel lo the high impedance slate by Bus Enable <BE). 

Ready (ftDY) 

Th>s bidirectional signal indicates that a wail far Interrupt < WAI 1 inatiuc- 

lion has been executed allowing the user lo halt operation ol the micro 



processor A tow input logic level will halt the mieroproce««r m its cur- 
rent stale |nme tnai wnen in the emulation mode, ine W65C902 stops 
only dunng a read cycle) Return .ng RDY to the active high stale allows 
tne microprocessor to continue following the nent Phase 2 In Clock 
negative iransiho-n The fl'DV signal is internally pulled low fallowing the 
e*ecu hon ot a Wart far Interr uptjWAJ | instruction, and then returned fa 
the high state when a RES, ABORT, NMI, or IRQ external mlerrupt is 
provided This feature may be used to ejirninat e inte rrupt latency by 
placing Ihe WAI instruction al Ihe beginning ol Ihe IRQ servicing routine 
I 'tie IHQ Disa ble liag has been set, thene«1 Instruction will be enecuted 
when in-B IRQ occurs. The processor will not stop after a WAI Instruction 
II RDV has been farced to a nigh n.io The Slop (STP) irtstrwciioc has 
no affect on ROV 

Reset (RES) 

The Resai input is used 10 initialise the microprocessor and starl pro- 
gram enecution The ftesal input butter has hyslereals such thai a simple 
R-C timing c-irc ui I may be used with the i nternal pul lup device The RES 
signal must be h«id low lor at least two clock cycle* alter Vdd reaches 
operating voltage Ready (R D V) has no effecl while «ES is being held low. 
-, Beset condrlioning period, Ihe following processor inilialna- 
lion lakes place: 

Registers 
D - 0000 SH = 01 

DBR - 00 y,H z oo 

PQR - 00 VH - 00 

N V M X D I .l" 



I 







* i ' - Not Initialled 



STP and WAI instructions are cleared. 
Signals 

e - i voa - o 

Mtt = 1 vp = t 

a-w = i upa = o 

jvnc o 

Whenfleset r* brought high, an interrupt sequence i* initiated: 
■ R'W remains in the high state during, ihe stack address cycles. 
• T he Reset vector address is OOF - F C D 

Set Overflow (SO)— W65CW2 

A negative transition on ih-s -npui Sen the Overflow <V| flag, b-l 6 ol the 

Processor Sialua (P) Register 

Synchronise (SYNC)— W6SCB02 

Tne SYNC output 'S provided to identity ihose cycles during which the 
microprocessor is letching an opcode Tne SYNC signal n high dunng 
an opcode lelen cycle, and when combined with Reedy (RDVl. can be 
used for single instrudion enec 

Valid D«|p Address (VDA) and 

Valid Program Addree* (VP»J— WB5CI1E 

Theea two output signals indicate valid mernory addresses wnen high 

(logic l ), and most be used for memory or t/'O address quaNfication. 



VDA 



WPA 





I 



1 







I 



internal Operation— Address end Da1a Bus 
available. The Address Bus may oe m»alid 
v"atid prpgrem address— may be used lot program 

Valid data address— may be used far dala cache 

control 

Opcode latch — may be used lor progiam cache 

control and single step control. 
Vdo and Via 

V^D is Ine positive supply voltage and V5S is system logic ground Pm2f 
o> me two V=s pms on the W66C802 should be used loi system ground. 
Vector PuH (VP)— WBSCB16 

T he Vecfar Pull output indicates Jhji a vet tor location u bai ng add ressed 
during an interrupt *equ«nce VP is low during the lasl two interrupt 
sequence cycles dunng wnicn time ihe processor reads the interrupt 
vector TheVP signal may be used loseled and ptiontize i iirir Jt ,iiir:,ni 
i ,[ r i Huron by m afi I , i • ■ <■■■ .. -i » tddreaaes 
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Table 1. WB5C816 Compatibility liaues 



W*5G81S'»02 


W65C02 


NMOS f 501 


1 S lSr»ck> 


Always page i i E 1 1 fl n 1 1 
16 bus when IE ■ 0) 


Always page 1. 9 bits 


Always pag* t. 8 oils 


2 X (X lr>d«« Re»i*lor) 


Indexed page zero al *»ays >n 

pug* |E - 1), 

Com p»ge I E 0| 


Always page 


Always page 


3. V (¥ Intfe* Regurterj 


Indeced page zero always in 

.page if 

Cross page |E - 0} 


Always pig* 


Alwayp page O 


a A | Accumulator I 


a bits <M 1|, tSb'IsiM =0) 


H bill 


H I: K 


J P (Flag n#gi*lD*J 


N , V. and 2 Hags vail -n 

]>■ .i ■• i ■ 

D - altar re*H at inienupt 


M V, and Z Hags valid in 

decimal mode 

D - altiv rnsel and 

interrupt 


fm. v, ana 2 nags invalid 

■n decimal made 

D - unknown alter reset 

D not modified alter interrupt 


6 Tirni'iy 

A ABS XASL L5R. ROL, 
ROR With No Page Crossing 

Jump Indued 

Opened xxff 
C Branch Acrou Page 
D Chromal Mode 


^ cycles 

5 cycles 

a Bydea i.E - ii 

3 cycles <E =0| 

No additional cycle 


6 cycles 

i, cycle* 

♦ cycles 
Add i cycle 


7 cycles 

5 cycles, and invalid page 

4 cycles 

No additional cycle 


7 BRK Vector 


0OFFFE.FIE 1 1 BRK bit - D 
on slack i* IRO NMI, ABCWT 
0OFFE6. 7 IE - 0) X - X on 
Siac* always 


FFFE.F BRK bit twi stack 
i1 fRO, NMl 


FF£E,F BRK tut - on stack 

,1 IHU l.f.'' 


. a Inrerrupi o» Break 
Ban* Address. 


PBR not pushed IE i| 
RTI PBR not pulled <£ - II 
PBR pusned <E ■ 0) 
RTI PBR pulled tE - Ql 


Not available 


Nol available 


9 Memory Leek |ULI 


ML ■ during Read Mod-fy and 
Wr ite cycles 


Ml - during Modify aid Wr»lB 


Not available 


id indued Across Page 

Boundary ld|y. a.» 4,y 


Emra road al invalid address. 
(Nona i 


1 .id of last instruction 
lelcn 


Enlra r«»d «' invalid address. 


11 HPY Pulled During Write 
Cycle 


Ignored (E • U lar W65CB02 only 
Processor slops |E 0> 


PrOGtlMOr Stops 


Ignored 


12 WAI ana SfP Instructions 


Avertible 


Available 


Not available 


13 Unused OP 


One reserved OP Code specified 
as. WDM will tie used in future 
system? TUft WBiCH16 performs 
3 no opera) on 


No opeia'.i'jn 


Unknown and some hang 
up' processor 


M Bank Address Handing. 




Nol available 


Nctf available 


16 WW During n*i4'Modiry- 
Wf»l« instructions. 


E t ww ; O during Modify ana 

Write cych*» 

E = WW - only during 

Write cyd* 


R IN only during Write cvcir 


R'W during Modi ry and 
Wnie cycle* 


16 Pin 7 


Wij-jCSOa STTKC 
W65C816 = VPA 


SYNC 


SYNC 


1 7 COP Instruction 

Signatures 00- 7F user delinks 
Signatures BO-FF reserved 


Available 




Nol available 



Noie i See Caveal section lot additional intormation 



Appendix 2 479 



W65CB02 and WB5CB16 
Microprocessor Addressing Modes 

Th* W65C81& n capable of directly addressing 1 6 MBytes ot memory 
Tti-ia address space nas special signifies nee withm certain addressing 
modes as lollows 

Rtnt and Interrupt Vectors 

The Reset and Inlerr upl vectors use the mainly of I he lued ■ddr<vss«s 

between OGFFEO and OOFFFF 

5l*ck 

The Stack may use memory Irom 000000 So OOFFFF The etloclnre ad 
d'es* 0-1 Slack anc Stack Relative addressing modes w>ll always be wiltim 

this range 

Dime) 

The Dirccl addressing mode* are usually used 10 Store memory registers 
and pointer* The effective address generated by Direct. Direct, X and 
Direct Y addressing moaes is always m Banh i'000000-OOf FFF) 
Program Address Space 

The Program Bank register is not a11ected by the Relative Relative Hong, 
Absolute. AbscHute Indirect, and Absolut* Indexed indirect Addressing 
modes or by incrementing the Program Courier Irom FFFF The only 
instructions thai affect the Program Ban", register are ATI RTL.JML, 
J SL. and JMP Absoi ule Long Program code may exceed 64K bytes ai- 
Ihough code segments may not span bank boundaries 

Data Addreaa Space 

The data address space is conlig uout in toughoul the 16 MByte address 
space Words arrays, records, oi any data structures may span 64 Kflyie 
Dank boundaries with no compromise in code elliciency The following 
dJdiessing modes generate ?4-on artactma addresses 

• Diracl Indaiad Indiroci <d «| 

• Direct indirect Indexed (dry 

■ Direct indirect I J 

• Direct indirect Long [flj 

a Direct indirect Long Indened |d|.y 

■ Absolute a 

• A&iu Iu1e a ■ 

• Absolute a,y 

• Absolute Long: el 

• AbeoJuTo Longi indexed al.» 

• Stack Relative indirect Indexed Id sl,y 

Tne loll o*i ng addressing mod* desenptrons provide additional d«1a> i as 
to how •Neciive addresses are calculated 

Twenty-tot* addressing mode* em available lor use with the W6SCB02 
and W65C81& microprocessor* Toe "long addressing modes may 6b 
used with the W65C802. ho*ever, me high byte of th* address rs not 
available to the hardware Detailed rJascrtplifini rjl the 24 aadre»a.ng 
modes are as follows 

1. immediate Addretsing — " 

Trve operand is the second byle (second and ihird bytes when in Ihe 
ie-b>1 model of the instruction 

2. Absolule— a 

With A bsolule addressing th« second and third bytes of the met rue 
tion lorm the low-onjer ie pits 0* the selective address The Data 
Bank Ftegisit" contains inn hign-ordar 6 oitsol the operand address 



Instruction 

Operand 
Addreia: 



opcode 

UBH 



addil 
addrh 



addrh 






3. Absolule Lang— al 

Tne second, tmrd arvd fourin byie at me instruction form me 24-tnt 
effective address 



when the Direct ftegusler is not page aligned ( DL not ecuai Of Tne 
Bank register is always 



Direct Register 
ctHael 



Djatrand 

Addren. 



u'Vi "i.i i :■• ■. 



S. Accumulator— A 

• 'm ol addressing always uses a single byte instruction The 
operand ■ Hie Accumulator 

E. Implied— I 

implied addressing uses a single byte instruction The operand is 
implicitly denned by the instruction 

7, Direct Indirect Indexed- (d},y 

This address mode i* often referred to as Indirect-* The second 
nyieot the instruction is added to the Direct Register (Dj The 16-on 
contents q1 this memory location is Jrien combined wilh ll»e Data 
Bank register io form a 24-bit base address The Vinde* Register >« 
added to the base address to torm ihe effective address 



instruction 


opcode 


011481 






Direct Register 




n 


1 offset 1 


! 


1 reel address 


men 






1 


00 


(direct addreaa) 


- 


DBR 


I 


1 




basa address 






! V Reg 


Operand 

Addreee- 1 




etteclive address 



. Direct Indirect Long Indexed — [dj.y 

With this addressing mode. the?4-pit base address is pointed to by 
the sum o« the second byte of the instruction and the Direct 
Register The elf sen** address is this 24- bit base address pi us tna *' 

»n ■' « ft ]«tei 



Instruction: opcode 



o'lset 



Direct R«g.»t«i 
♦ 0TTMI 

DO dnecl address 

(direct addrCSSI 



VRagi 



Operand 

Addm.i. 



effective address 



I 



Operand i 

Addreta: ' rtaddr I addrh aetdri 

4. Direct— d 

Tne second Dyle of fne instruction a added loin* Direct Register 
I'D I Io 'aim ihe etfeclive address An additional cycle is required 



9. Direct Indexed Indirect— {d,»)i 

Thi* addreaa mode is often referred to as Indirect. X Tne second 
byie ot the instruction is added to the sum of the Direci Register 
31- d ihe X inde* Register The result points to the low-order 16 bits 

Of the effective address Tne Data Bank Register contains [hah ig*- 

oroer B bits 01 the eiraehv* address 
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HalnidtaA: opcode 



Dirtct Register 

I a"se1 



direct address 
t x Rag 



n 



address 
(sdtfre**) 



DparaNd 
Address: 



B-Het:liT# aOdfCBi 



ID. Dlre-el Indexed With X— d,x 

The second byt eef the instruct ion is added to the »um ol Ihe Direct 
Register and «h* X Inde* Regiate* to lorm the tS-bit eff*ct»f# 
address The operand is ihrty* >n Bank Q 



Instruction; opcode | offset 



Operand 

Addi.ii. 



Direct Register 
orlMl 

aired address 
KRag 

etlectrva address 



11. Dlr»cl Indexed With Y— d,y 

ma ".i>i i! 1 1 .1-' l i ma > mruci on -• added u lha lumal Ihe D mil 
Register and the V lnde» Register to torm ihe 16-tWI ellecHre 
address f n« operand is always in Sank 



|r, t lrucllon 



Opcode 



D.rect R»gi»i*+ 

I offset 

d.rect address 



Operand 

Address 



DQ 



Olfncdve add'M* 



12 Abtolutt Indexed With K— ■»! 

Th» second ancr third bytes of ins instruction aia added lo the 
X Inden Register to lorm the low-order tfi tuls of Ihe effective ad- 
drew The Dal* Ban* Register contains Ihe high-ordero b>l*«'me 

elective address 



Instruction 


opcode addrl 


addrn 




DBR sddrh 


addn 
X Reg ! 


Operand 
AOdrm 


I 

ettetiiee address 


I 



13. Absolute Long Indexed With X— al.a 

Theiecond third and fourth bytes ol the instruction forma 34-tnl 
Das* address The anecirve address is the sum ol ln» 2+> bit add res* 
and the X lnde> Register 



Instruction: 


opcode | uddrl 


eddrh 


baddr 1 




Daddt 1 addrn 1 


addrl 
, F*ed 




Operand 

Add* see; 


effective address 







14. Abaolule Indexed With Y— a,y 

The second and tmrd byies ol ihe instruction e>* added lo Ihe 

V lnd»« Register to lorm the low-order 16 tuts ol the effective ad- 
dress The D«l»BanK Register contains the high-order B biiso' the 
e'fective address 



Inn ruction; 



| opcode [ addrl idtfr' 


our addrn addrl 

*l 1 VBeB 1 



Operand 
Address: 



effective address 



15. Program Counter RolstI**— r 

This address mad*, referred to as Relative Addressing, is used only 
with the Branch instructions ■> the condition being tested is met. 
the second byto of in* Instruction is added to wo Program Counter, 
which rus Been updated lo point to the opcode of thenent instruc- 
tion The offset ■• a signed 8-bil quantity mine range horn -128 lo 
127 The Program Bank Register is not affected 

16. Program Courtier Relative Long— rl 

Th«s address mod*, referred to as Relative Long Addressing, is used 
only with the Unconditional Branch Long instruction (BHL) and me 
Push Effective Relative instruction (PER) The second and third 
Dytes of in* instruction are added to the Program Counter, wmch 
has been updated lo point to the opcode o1 Ihe next instruct ion With 
the branch instruction, the Program Counter w loaded with the 
result. With the Push Et'ectn/s Relative instruction, the result M 
Stored onth* stack The offset isa signed 16-tHi quantity in the range 
iiom -32768 to 32767 Th* Program Bank Regisler is not affected 

17. Absolut* Indirect— (a) 

The second and third byies of Ihe instruction form an address to a 
pointer m Bank 0. The Program Counter <s loaded with the tirst and 
second bytes althis pointer With Ihe Jump Long |J ML) instruction, 
lha Program 8ank Register is loaded with the third byte ol the 
pointer 



Instruclton: opLt>de 



addrl 



addrh 



Indirect Addrass= I 00 I addrh I addrl I 

New PC * (indirect address) 
with J ML 
New PC - (indirect address) 
New PBft - imdirect add i ess *2J 

18. Olracl Indirect -(d) 

The second fiyteol' the instruction is added 1c ine Direcl Register i-_i 
lorm a pointer lothe low-order 16 bits o' the effective address The 
DM Bank Register contains the high-order 8 nils of me erlocirva 
address 



Instrveiton; opcode 



otfss 



Direct Register 
I oifset 



Operand 
Address- 



00 I 


direct address 


00 I 


(ui'ect address) 


DBR 1 





.('►,■[- ii.r iddteti 
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19. Olrect Indliacl Long— (d) 23. Slack Relative Indirect Indexed— (d,B),y 

The second oyte of «h« i isif action 15 added 10 me D. race Reg. Her w The second byle ol W* instruction b added 10 the Stat k P01 nler 10 

form * pointer to the 24-b.t eitectiye address lorm a pc-nter 10 the iow-o*de« l6-b<l base address in Bank The 

I . . Data Bank Register contains lt>a high-order B b«ta ol The fiaie ad- 

■nilnjcllon; | opcode [ otlset cress The effective aao re»9 is me sum 01 me 24-Bii oesa address 

ami Ihe ¥ I ride* Register 



Direct Reg«»ier 
ollset 
00 direct address 

Ihnn 

Operand . , 

Addrees: (direct addra»| 

20, Absolute Indened Indirect — (a.jr.) 

The second and third bytes or l«e instruction are added to the 
X mden Register to form a 1 5- bil pointers Bank The contents gJ 
this pomterarekoaded in the Program Counlor The Program Bank 



Iniliucllon 



opcodo plll.t 



Reg (Sl«« .1 not changed Da%m -BdrtBI 

instruction: [ opcode addrl addrn | « 



V R»9 



XR«9 



Operand . 

Afldr ■■■. effects* »ddrcis» 

24. Block Source Bank, Dentin ation Bank— *ye 

PBR address This addressing mode is used by Ihe Block Move instructions. The 

second byte of the instruction contains the high-order S bits of Ihe 

*"""• destination address The Y md*« Reoisiei contains the ton -order 16 

PC ■ (address) bits of trn» destination »ddre*» Th» third byte o* the mslr uetian 

contain* Ihe high-order t oil* ol the source addre** Th* X Indo* 

21. Stuck — t Reg isle' contains the low-order 16 bits of the source address The 
Stack addressing relers loan instructions mat push or pull dala c Accumulator contains one less than the number of bytastamOTie 
Irom the slack, suchasPush, Pull J umplo Subroutine. Return from Ttie second byte of ihe block move instruction* it also loaded into 
Subroutine. Interrupts, and Return from rnlerrupi The bank ad- the Data Bank Register 

dress rS el waySO IrilBrlupr Vfrttbri urn always torched liom Hani Q r ; 1 T~7T~l 1 1 

Instruction: | opcode | dslbnk | stebnk | 

22. Stack Relative-eve dJlbM . DBB 
Tna inw-orour 16 bits ol me ?rfeciiue address is lormeo from irw Source 

sumollnesecondOrteoftneinsliuGliLinandiheSiackPoinler Tr>e Address: I ncbnk | X Heg 

hign-order 6 bits ol the effective address isal#aysiero fhe'elative OmBneilon 

o" set is an unsigned B-bti quantity in the range ol to 255 Ai4d , M( DQH '•' Flea 

instruction: | aneaae [ unset ' Increment (WVNI or decrement iMVP) X and V 

Decrement C («f greater than iero), then PC *3 - PC 
Stack Pointer 



Operand . , 

Addrtic DO effective address 
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Table 2- VY6SC802 and WB5C816 Instruction Set— Alphabetic*! Sequence 



ADC Ado Memory 10 Accumulator with Carry 

AMD 'AMD Memory *"'ri Accumulator 

ASL Snili On* Bit Lsrt, Memory or Accumulator 

BCC Branch or> carry Clear 

BCS Branch on Carry Set |l 

BEQ Branch il Equal fP/ M 

BIT B.tTesl 

Hw Branch it Result Minui (Pn 1| 

BNE 8/anchilNoiEnu^i P 

BPL Uranen «l RimuIi Plus iPm ; 01 

■ .■ i ... , 

BRK force Break 

BHL Branch Always Long 

B VC Branch on Overflow Clear | P» ■ 1 

BV5 Branch cm Overflow Set |Pv 1 1 

CLC Clear Carry Rag 

ClO Clear Deo ma 1 Mode 

CLI Clear Inieirupt Disable B-l 

O.V Clear OvoHltm Flag 

CMP Compare Memory and Accumulator 

COP CoproCBS&O' 

CPX Compare Memory gnd indei X 

CPY Compare Memory and inde» V 

DEC Decremani Memory or Accumulator by One 

OEX Decrement Inoen K by One 

DEY Decrement lnoe« Y by On* 

EOR E«eiu*i»* OR Memory wiin Accumulator 

INC incrjjmo-nt Memory or Accumulator Dy One 

INX increment index x By one 

IWV ineremeni Index v t>y One 

JUL Jump Long 

JMP Jump la N#* Location 

J5L Jump Subroutine Long 

JSP Jump to Nhjw Location Sav.ng Return Address 

IDA Lead Accumulator with Memory 

LDX Load Index X w-lh Memory 

LDY Load Inde* V v«'th Memory 

lSR Strfl Ono Bit Right IMe-mory or Accumulator) 

MVN B-lottMowe Mogul me 

MVP Block Move Positive 

NOP No Operation 

QUA OR M*rei©ry with Accumulator 

I uafi Effective Absolute Address on Slack (or Push In 

Data on Stack i 

PEi Puwi Eileen ve Indwecl Address on Slack ick Pvsn Oirect 

Oaia on Slack i 

PEft Push Efreclive Program Counter Relative Address on Stack 

Foi aiiarnele mnemonics, are Table T, 



PHA Push Accumulator °" S1fle * 

PhB p js»* Data Bank Regisier or* Stack 

PMO Push Direct Register oi- 

PHK Push Program Bank Register en Slack 

PHP Push Processor Slal us on Slack 

PHJt Push Indei X on Stack 

PHY Push Inde* v on Slack 

I' LA Pull Accumulator from Stack 

PLB Pull Date Bank Register I'rjm Slack 

PLC Pull Oirpri Register trom Stack 

PLP Pull Processor Status irom Slack 

PLX Pull tide* x from Slack 

PL* 1 f ' f m Slack 

REP Resei Staius Bits 

ROt Hot ale One flit Lett | Memory •■> 

ROB Rotate One BH Rrgnl (Memory ck Accumulator! 

R f i Hn mn bom Interrupt 

RTL Return Irorn SuO-routin-a LerMJ 

RTS Return Irom Subroutine 

- i Memory from Accumulator m" 

SEC Set Cart") 

SEO Sel Decimal Mace 

SEI Scl Interrupt Disable 5lalua 

SEP Set Procr> or status Bile 

FTA Store AccumutelOf in Memory 

STP Stop the Clock 

SIX Stew* Inde* X m M«im.-iry 
Slur*) Index v m M*mcry 

STZ Siore Zero in Mertiory 

IXK Ttanslei Aocuro«jlal»i to lnde< X 

tflv Transfer Accumulator \a ind«« V 

TCD Transfer C Accumulator 1o Direct Register 

TCS Transfer C Accumulator to Slack Pointer Heo/isler 

TOC Transfer Direct Register to C Accumulate* 

TRB Tcsi and Reset Bit 

TSB Tost and 5e; Bel 

tSC I'ansler Stack Pointer Register io C Accumulator 

TSX TraJisJe* Slack Pointer Register io Index X 

T XA Transfer Indei X to Ace umuiator 

TXS Transfer Indei X to Slack Pointer Register 

TXT Transfer Inde ■ X 1q i 

TVA Transfer Indei V io AocurnulitO" 

TVX Transfer Inrjem Y Io Index X 

WAI Wait lor Interrunt 

WDM R«s*rvea tor Future Use 

XBA, Exchange B and A Accurrii 
XCE I nry anaEmulaiion Bits 



Table 3. Vector Let-cations 



OOFFFE.F i RQ.BR i; 
OOFFFC.D RJ 
OOFfFA,B- NMl 
OOFFF8 9 -ABORT 
OOFFF6T -IHeserw?cfl 
OOFFF45 -COP 



Hardware, Sufi* J re 

Hardware 

Hardware 

HU I-'- 9 ' 

Sottware 



OOFFEE.F -IHO 
OOFFEC.O' (Res et wed) 
OOFFEA.B- NMI 
OOFFEB.9 — ABOHl 
OQFFE6.7 -BFtK 
OQfFEa.5 -COP 



Hardware 

Hardware 
Hardware 1 

software 

Sn-'A'.ire 



Tne VP ouipui is low during im> two cycles used 'or vector location acceaa 
wnen an inrerrupl is eneculeO. D ; D and I - I in Status Register P 
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Tabfc 4. Opcode Main, 




■ynM 


aodrmtng mod* 


•fmbot 


■ddrniJnfl mod* 


■ 


'!-T*0«ila 


M 


Sifsel lOdircd king 


* 


ACCUTOjIlSOl 


Hi* 


*f»c1 indiroct long indexed. 




program coun|*< retain.. 


a 


abjo'ulo 


rl 


program couiMnr rclativ* lanj 


«.» 


ibKMa^m.w i,,!' . 




imphM 


«!■ 


•bfcaluM ind«<«a IWIIH Tl 


% 




M 


*bwiM» lono 




Li"HCl 


*> t 


♦C-SOluIr lor-a indaiad 


d.. 


dnact inon.Kl |-ii, >| 


di 


1'0L« rrlilivo 


At 


d.«e> maekri ) wlh yl 


«.i>r 


•tick mialivg .ndirecl mdextc 


<d) 


d"*cr iw«i 


in 


aaiolule inducer 


|4U1 


'Jceiil mde^nd inaninri 


llll 


■Cltolult •ndeiBd indiracl 


(•l.» 


dirccl indi»«ei iftitjiiad 


■ v.: 


Met mouB 



INSTRUCTION 
MNEMONIC 



BASE 
NO BVTES 



Op Code Malrii L*fl»nd 



# Now W66CB16>'B02 Opco-ttoi 

* SJ«* W«SC02 Opcodw 
Ql.ink = NMOS 6502 Opcode*. 



ADDRESSING 
MOM 



BA!,f 
NO CVCLES 
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JkOC 

ASI 



BRA 

aa. 
:ui 

•■;:. 



of 

I .<> 
INC 



. [IV 
LSR 
M'.N 
MV* 



Nor 
OR* 
I* 



PWb 

rHP 



Table 5. Operation, Operation Code*, and Slatm Regj.ter 



: J HiI .•■ 



* 'M.C -A 
>■'■>'• 
HflA'li":- I 
9BANCH If C • ' 



BRANCH IF Z ' I 

AAMlWOIt l| 
MUNCH IF N • 1 

«*amch if j: a 

MKMCH IF N - 



9KA.NUn ALWAYS 
BREAK INOTE 3| 

6RWICI' lomj »i*«; 

BRANCH i | 
BRANCH If J 1 



tt-C 

c - :> 
o- i 
e - v 



CO-^OCESdOP 



. i - 

A-rM ». 

K.I - * 

T - I ■ r 



AIMPlONG TO NEW IPC 

JUMPTG *s*ru3C 

l.. t - ■, . I 
jump to ma 

u - * 



M - II 



"al -c 

U M Ml .ii M 



,,-., PftMTICM 

MM A 

■ 

Will; U)il ' li V 



»..% 



IT 



A -Ml 5 

OB" Mi 

Jj - Ml Wl - 1 S - * ' 

PBB - Ms. S - I • & 



< - Ml I 

» M, S- 1 J 

S-l i U. -A 

f. ■ I a *»• - 0»R 

S • 9 -5 Ui I Urn ■ O 




T«S 

toe 



• n 

I-* 



liTRh FROUl^r 

hTRN FnOMSVft 10NO 

RTHF. jUfinCFjTlnE 



suikm 



r 



■ ■ 

NO OPERATION |FIE.5f Vlt>l 



■ 



? 3 



-- s. 



am 

1 = - 

B« 

■C . 



-ik. 
B¥C 



COP 

cm 

cm 
ate 



10* 
LOT 

win 



no* 

0*A 
FtA 



F-* 

fu 

FS.D 



S y M ■ D I I C 



2 C 



m i :. . JCi 



PIP 
PLJt 

.■L. 
«P 



RTl 

RTE. 



I- 
»TJ 

-*■ 
TAt 

•;:l 
- ZS 

TDC 



I tlXan M 



ml *j i in 



• >M. A-15-:JTJ IBKibClloni 
gi,-. NM05 sw: 
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Table 6. Detailed Initrucllon Operation 



liOY CP* cpklDkoma 
CaA»yicnSP5«;Pl 



'. *,.*ut.ir* iddaiupui n.->i »j» 

I l-BK Pi; 0|| CjK» 

1 ft • HRK.-I IDl 



iBiTiTysr/iBt 

-i . ' ■ 

-,,,..,: i. I 

1TMM ■■■• 

.'* .;. Qaclai 



,. . . - - -. 

nec inc Tin rMn 

>r, . .. I„ 

llCW 

*01f Jin IJ-japPl I 



III !■■ - I 

|jf,0 

■-■-I- 



- 

* una*:' 

LtOpC -'"- 
i«fcfta»i 

- 

i«< 

■ '_ i. .* 



[ «u->uH t ana. . Ju-i|> hi 
Suvnuliwl vgl M 
|MU 

' 'v ...»« I 
i ,1.. 



CaVJiNDiaK t3L 



.AILPEa. lVH»Lin 

--J'-ii 



•- ■■ 



■ 



.■ 
■fc -*u-K)l 



na 




i 


..; C -!» 






• 1 a-TAl 




I 






' 


-.i ,, •- , . 






■ 






.. c -,,, 






HIT*). 




• 


1 .,_«, 




«» M 

■ i" : • 

■ 




'1 - 





»*ii PC 


Op Cow 


■i-dp pc-> 


ML 


PUP POJ 


*Ax 


0*».A» 


rm.io. 


;*>»•-• 


Ml " ■■ 



o ciimaa 

u ce*ii».i 

DBPAa-l 

n nun a* 

i P«m K 

. ._., . . 

1 PA* PC-' 

i i-e* Nt*" 



i 



pew • 



ID 

cuu ~ a » 

am in* 

': ' ■■' 

(at a ac-i 
mm p.- - 
,■ [ ... 

■ : C -:- 
•** "i- 
KV M 



. i. . ; 
...... . . , 

Atft u 

1*1; Jl . 

p»w»n 
p»M»o> 
■-,>> I .. 
p*A,*CO 
Mi W "3» PC 



**is fr.. 

*** •* 
Onto* 



■rt* PC. 

HA * PC - 

p»» 



NIWPTW'C 


■mtosc 


pap i 


1 . ■-■» 


■:... ; 


oo 




o 


ID-DO 


DM iu> 


aO-QO-i 


. . ■ - j' 


- .- !• 


.-■, C** 


-->-• ■ 


» 


•SOUf-i 


• :■ 




Dm iu- 




« . - e 




a 


nnono 
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Table 6, Detailed lnitruct.t>n Operation (conlinued) 
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Recommended W6SC816 and W65C802 Assembler 
Syntax Standard* 

Dlnfctlvea 

Assembler direct ives are those part* ol me assembly language source 
program which give directions io the assembler, this includes the defini- 
tion or dais are* and constants within a program Tnis standard excludes 
any definitions of assembler directives 
Comments 

An aswiDle' should piovidea way to use any iineol mo source program 
as a comment The recommended way of doing inn it to treat any blank 
line, or any line thai sinns wnn a semi -colon or an asterisk as a comment 
Other special characters may da used as wen 

Th* Source Line 

Any line which causes the generation ot a single W&5C8I6 or W65C802 
machine language instruction mould be divided into lour tieids a label 
field, me operation code, the operand and me comment field 

The Label Field— 1 ne la Del held twgins in column an* of tn* I mo A label 
must start with an alphabetic character and may Da followed oy zero or 
mare alohanu menc characters An aiMmoier may deli ne an upper limit 
on the num ber ol characters that can be in a label . so long as mat uppei 
I imii is greater man or equal io six c iwbc leu An assembler may limit 
rnc alphabetic characters to upper-ease character* ii desired 1 it lower 
case characters are allowed, they should be treated as identical tomeir 
upper-case equivalents Other characters may be allowed in the labet.so 
long as their use does not conflict w ith the c oamg o' operand fields 

The operation Code Field - Th* oparalion code shall con»»t ol a I hre« 
thai acta* sequence <mnemonic) from Table 3. II shall start mo sooner 
than column 2 o' the line, or one space alter the label if a label is coded 

Ma ny ui i he operation codes m Table 3 haw duplicate m namontca, when 
two or more machine language instructions have ihe same mnemonic, 
the assemble' resolves the difference based on m* operand 

II an assembler allows lower-case lellets in labels, it must also alio* 
lower-case letters mine mnemonic When lower-case letters, are used in 
ihe mnemonic they shall be treated as equivalent to the upper-case 
counterpart Thm. the mnemonics LOA. Ida. and Ld*musl all be recog- 
nized and are equivalent 

I n aodi I ion to ihe m nemonics shown in Table 3, an assembler may pro- 
vide ihe alternate mnemonics shown in Table 6 

Tabla 7. Alternate Mnemonics 



Standard 
BCC 

Bl-.S 

CMP A 

OECA 

INC A 

J&L 

JML 

TCD 

TCS 

TDC 

TSC 

XBA 



Alias 

BLT 

BGE 

CMA 

DEA 

MA 

JSH 

JMP 

TAD 

TAS 

TDA 

TSA 

SWA 



J SL should be recogn ized as equivalent lo JSfl when it ra specified wilm a 
long absolute address JML is equivalent lo JMP with long addressing 
toeced 

The Operand Field— fr-.e operand held may start no sooner man one 
space after me operation code held The assembler must oe capable ol 
al least Iwt nty-lour bit address calculations The assembler should oe 
capable al specifying addresses as labels, integer constants and neaa- 
decimal constants The assembler must allow addition ana subtraction 
in in* opera no field Labels snail t*e recognized by tnefact matmey start 
alphabetic characters Decimal numbers snail be recognised as contain- 
ing only me decimal dign* 9 HeaadeomeicOnstiintsshalioerecog- 
niied by prefixing the constant with a "( character, loilowed by zero or 
more of either the decimal digits or Ihe heiadec>mal digits A" F if 
lower -case letters are allowed in the label field, men they shall aJso be 
allowed as neaadecimai digits 



Ml Bdmimti.no maiin- what the«r format, *hal i provideal lean enough 
precision to specify all value* thai can be represented by a twenly-four 
tut signed or unsigned integer represented in two's complement notation 

Table 8 shows me operand formats which shall be recognized oy tha 
assembler T he symbol d is a label or value which the assembler can 
recog nizo as being less man S lOO The symbol a is a label or vai ue which 
the assembler can recognize as greater the $F F but lasts than J 10000. the 
symbol al is a label or value that the assembler can recognize as being 
greater than SFFFF The symbol EXT is a label which cannot be located 
by ihe assembler at tne lime the instruction is assembled. Unless in- 
structed otherwise, en assembler than assume that EXT labels are two 
bytes long The symbol* r and n* are B and IB bit signed displacements 
calculated By Ihe assembler 

Note mat the operand does not determine wheih*r or not immediate 
addressing loads one or two bytes, this u determined by the selling ol 
Ihe status register This torew the rerjui rament for a directive or directives 
that led the assembler to generate one or two bytes ot space tor retime* 
diale loads The directives provided shall show separate sellings lor the 
accumulator and index leys'trs 

The assembler shall use me < --. ana * characters after the a character 
•n immediate address to specify which byte or bytes will be selected from 
ine value 01 the operand Any calculations in the operand must be per- 
formed before the byte selection lakes place Tab le 7 dei>nes the action 
taken b f each operand by showing the effect ol the operator on an ad- 
dress Thecoiumn thai showta two byte immediate value show I no bytes 
.n the order m which they appear m memory Th* coding ol the operand 
is for an assembler which uses 33 bit address calculations, showing Ihe 
way that tr>» address should be reduced to a 24 bil value 

Tab)* 8. Byla Selection Operator 



Operand 


On* Byte Result 


Two Byte Rei 


•J0102O3O4 


04 


CM 03 


#<K>l<3*0304 


1.14 


04 03 


. 101020304 


09 


03 02 


• 'MiaaoatH 


02 


02 01 



Initny location man operand where an andress. or expression resulting in 
an address, cart be coded, me assembler snail recognize I he pref >a char- 
acters -:M . and :■, which force one byte (dxeci page), two byte (absolute) 
or truee byte (long ahsoiuiei addressing incases where the addressing 
moeM ii not forced, ihe assembler shall assume ihei the address is two 
bytes unles* Ihe assembler isabietodetermineineiype of addressing re- 
quired by context m wh<ch case thai addressing mode wilt be used Ad- 
dresses thai' be I tu ncated without error if an addressing mode <s forced 
which doe*, not require the enlue value of the address For example, 



LDA $0203 



LDA IJ01Q203 



are completely equ iva lenl If tne addressing mode is net forced, and t he 
type of addressing cannot be determined from context, the assembler 
shall assume that a two byte address is to be used 1 1 an instruction does 
not have a short addressing mode (as m lo a whi ch has no direct page 
indexed by Y f and a short address is used in the operand, the assembler 
shall automatically extend the address by padding the most significant 
bytes with zeroes m order to extend the address to the length needed As 
witn immediate addiessmg, any e>pr«saion evaluation shall take piece 
before ihv address is selected, thus, the address selection character rs 
only used once, before the address of expression 

The ' leaclanuriien pomti character should be supported as an alternative 
to the I Ivertfc-ai Dan 

A long indirect address is indicated m the operand field of an instruction 
by surrounding the direct page address where the indirect address, is 
found by square brackets direct page addresses which contain sixteen- 
bi-i eddresse* are indicated by being surrounded by parentheses 

The operands Ota block move instruction era specified aa source bank. 
destination bank— Ihe opvoaite order of ihe obtect bytes generated 

Comment Field— f ne commen I field may start no sooner than one space 
alter the operation code held or operand field depending an ■ nsvuciidn 
iy» 
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Tabic 9. Address Mod* Formal* 



Ad*«*lrvg MOO* 

Immediate 



Absolute Lang 



direct Page 



Accumulator 

Implied Addressing 
Direct Indirect 

indtfiteo 



Direct Indirect 
Indexed Long 



Direct lnd*i«4 
Indirect 



Direct Indexed by x 



Direct Indexed 6y V 



Anioiule <nde*ed try X 



■1 

•■I 

•ext 

•<a 

*■.* 

•<al 

« -j 

■ -a 
*>al 

« ejtj 

•Ad 

» ■■ ■ 

■ Hal 
*A6XT 



M 

'EXT 

£KT 

■d 

■ 

*| 
•I 

■EXT 
d 
<M 

3 
■I 

EX1 

A 

(no gperand) 

IdJ.y 

KHJjr 

i .in , 

. ExT;.y 

lai.v 
I- -»]>■ 

i- «h 

|<EXTJ.y 

.;o«| 

I ei.-i 

d,« 

J ■ 

M 
• ai» 

<exT,< 

t r 

-dy 
<al,V 

<-EXT.y 

d.x 

id,* 
■.« 

IB.R 

•al.« 

'EXT.n 

EXT.i 



AdrJreiiing Mfrdt 


Formal 


Absolute inde»«d By V 


'■ 




«* 




ay 




la.y 




'aly 




'EJCTy 




EltTy 


AMOiirie Long indexed 






■a, i 




■ 




al,» 




IXT,* 


PflSfiffHI OOUI 1--' 


) (lr»e assembler calcyUtes 


Brrlcifiwc ai"id 


a r*ndrt| 


Program Counter 


al 


Relative Long 


6X1 


Abiulu'.e l<td>recl 


(01 




<'d| 




' 




!'•) 




fall 




IEXT> 


Direct Indirect 


Idl 

I a) 




i di 

1 EAti 


: ii i '■■■ !.• '■■; 


[d| 

i .ii 




I ai| 




t;..i| 


Absolute Indexed 


Ift*) 








la.i 




IMUt) 




1 




|EXT»| 




i'EXT.h 


Stack Addrm>ng 


trio operand) 


SUB) Ral ii ■■■ 


(tf.«).y 


Indirect IndenMl 


K**.V 




|<**).y 




|--ai.*|i.y 




<-fcXT,S}.» 


Block Move 


a,d 




:..i 




del 




d.EXi 




».d 




M 




a.-i 




a.EXT 




•l.d 




■l,i 




al.al 




■I.EKT 




EXT.O 




EXT.a 




EXT.ai 




EXT EXT 



Note. The aJtorrsale ' |«c«mation po«ni| .a used in pi*w ot the | <verl»cal bar, 
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Tito* 10. AcktrHilna Mod* Summary 





Instruction Times 
In Memory Cycle* 


Memory UlrHuUon 
In Number ol Program 


Add ■•■■Mod* 


Origin*! 

■ BltNMOS 
4502 


He* 

WiSGfllB 


Origin*) 

• BHNMOS 

MM 


Mm 

WlSCtll 


1 Iti mediate 

2 Absoluts 

3 Absolute Long 

4 Dlretl 


2 

4 n 
3« 


4rMj 
jdW si 


2 

3 

2 


2JS| 

3 

4 


5 Accumulator 

6 Implted 

f Diri'Ti Indirect lnd*i«4 Idi y 

8 Direct Indirect Indexed Long ja|.y 


9 

a 

5 'i 


3 

2 

513*1 


1 
1 
2 


1 
1 
2 
2 


9 Direct Indemrd Indirect ld.i> 

10 rjir*ci.X 

11 Diretl ¥ 

12 AtMWull X 


B 

in 

4 

4Wii| 


&■■'" 
4 (Mil 

J li 

44 1 ill 


2 

2 
? 
3 


2 

2 
? 

3 


12 Absolute Long, X 

14 Absolute, ¥ 

15 Relative 

16 HeJaliv* Long 


« n 


51). 

«i U) 


3 
3 


4 
3 
2 
3 


1 7 AOsoiuie Indirect (Jump) 

IB Diied lirJuecl 

19 Direct Indirecl Long 

30 Absolute Indened Indirad IJump.i 


5 


5 

51141 

gl**l 

6 


3 


3 
2 
2 
3 


21 Stack 

22 Stnck Relal'ue 

23 Stack Relative indirect Indexed 

24. BiocK Move K, V C (Source. Desn nation Block Length* 


3-7 


3-8 

401 
7"i 
7 


1-3 


i 4 
2 
2 
3 



1 Page boundary, add 1 tyetoil page boundary is trussed when lorming addr*s» 

2 Branch taken add 1 cycle il oranch i* token 

3 M ? or X : 0. 16 bit operation. *dd l cycle, add 1 oyt* for immediate 
* Direct register low (OL)jiot equal two add 1 cycle 

S Read-Modif, -Write, add ? cycles tor M- 1, add 3 cycles for M • 
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Caveats and Application Information 

Stick Addressing 

When in Ihe Naliv* rnude, the St»ck may use memory location? 000000 
to 0OFFFFF Tne effective »dd«=« a! Stack, Slack Relative, and Stack 
Relative Indirect Indexed add'sssmg modes mil always be witnm thie 
range In the Emulation mode, the Stack address range ia 000 1 00 to 
000 IFF T ne fallowing uptimes and addressing moojBS will increment w 
oecrenwii beyond mis ran go when accessing two o< three oyle* 

JSL. JSR(a.x), PEA. PEL PER PHD. PL0. RTL d.l. Id.sJ.y 

Direct Addressing 

Tn* Direct Addressing mode* are often used lo access memory reg is4e> s 
and pointers The effective address generates by Oiract. Direct.X and 
TJ rrci i .Tridrcus-in^ modes will always D« in rna Native mode range 
000000 to OOFFFF When in the Emulation mode ine oireci addressing 
range is 000000 to QtJOOFF. except few [Direct] ana |Direci|/» addressing 
mode*, and the PEI instruction which will increment uem 00Q0FE or 
OOOQFF mia tne Stack area 

Bit Emulation mode and DH i* not equal lo *ero, live direct 
aadressi ng range a 00OH00 lo OODHF *-, e» cept tor | Direct | and |Dnect| v 
addressing model and the PEI instruction which will increment lipm 

If OODHFF i nln the next higher page 

Wnpn in Ihe Emulation mode and OL III not equal to loro the direct 

addressing range it 000000 to 00FFFF 

Absolute Indexed Addressing [W65C816 Only) 
The Abao'uie Ihdexed addressing modes are used to address data out- 
side the direct addressing range Trie W65C02and W6SCS02 addressing 
range is 0000 lo FFFF indexing from page FFKX may result in a OOvv 
data (etch when using the W6SC02 or W65C80^ Jn e&ntr&st, mdex.ng 
from page ZZFFXK may reauil in 2Z*l.O0Y"r wh»n using the W6SC81B 

Future Microprocessors (I-*-, rV65C»3Z) 

Future WDC microprocessors wi«l suooori ailcuneni W65C8I6 operat- 
ing modes for both* index and oft set add res* generation 



ABORT Input (W65C816 Only) 

ABORT should pe new lowtoraperioanoitoejiceed one cycle Also, if 
ABORT isneldlow during tiWADarl I nterru.pt sequence the Abort Intat- 
rupi wiHbe a b&rted it is not reeomrJi#ndea to abort the Anort Interrupt 
The ABORT internal latch isclaare a du ring tne second cycle ol ihe Abort 
interrupt Asserting the ABORT input alter Ihe following instruction 

cycles will cause registers to be modified 

- n«ad-ModirY-Wrl«e; Processor status modified if ABORT i* asserted 

after n mpdily cycle 

• Rll: Processor status; leWl i 1 ABORT is asserted after 

cyc le 3 



• IRQ, NMI. ABOUT BHK. COP. When ABORT isaaneried after cycle 2. 

PBR and DBH will became 0Q (Emulation nvodW) or »&R will become 

00 (Native mode) 
The Abort interrupt has be en dasig ned lor virtual memo ry ayslerra For 
I his reason, asynchronous ABORT'S may cause undesirable result* du* 
lo Ihe above conditions 

VDA and VPA Valid) Memory Addrtai Output Signals (W6SCB16 
Only, 

When V DA o> VPA are high and d ur«ng all wn le cycles. Its Address Bus 
is always valid VDA and VPA *JiouW be used to q uali fy all memory cycles 
Note that when VDA and VPA are both low, invalid addresses ni, oe 
generaied. Trve Page and flanx addresses could also turinvahd This will 
tie due lo low Byle addition only. Tna cycle when only low byte addition 
occurs is an options i cycle tor instructions wn ich read memory when Ihe 
index Reg isie-r consists of a Dits This optional cycle beecrmes a standard 
cycle far tne Store instruction, all instructions uamg Ine 16-Qit inden 
Register Aiode and the Read-Moaily-WritB instruction when using B- oi 
16-bif Inde* Rag 

Apple II, J la. He and 11+ Diss. Syaiama ( W65C«16 Only) 
VDA and VPA should not be used to quality add raises du ring disk opera- 
tion on Apple systems Consult your Apple representative lor hardware.' 
software configurations 



DB/BA Operation when ROY Is Polled Low (W65C8 16 Only) 

When ROV is low, ihe Data Bus <a held m the data tranjle' slaie |i e . #2 
higni The Bank address external transparent latch should be latched 
when the o>2 clock or RDY is low 

M/X Output {WSSCaie Only) 

The M,K oulpul reflects the value of the M and X bits ol the proceasor 
Status Register The REP, SEP end PJ.P ins1rucl»ons may change the 
state or the M and X bits. Note thai Ihe M,X output a .m/alid durmg Ihe 
n cycle lol lowing F1EP. SEP and PLP instruction execution 
This cycle is used as the opcode letch cycle ol the next instruction 

All Opcodes Function In AH Modes of Operation 
II should be noted that all opcodes function -n alt modes of operation 
However some instruction and addressing modes are intended rot 
W&bC8i624-oit addressing and are therefore less useful lgrtheW65CBG2 
ihe following is a list of instructions, and addressing mode* which are 
primarily intended lor W65QS16 use 

JSLPTi. ii| [rj| f JMPal, JML a i, Bi.» 
Ihe lolkowmg irntriictiona may be used wrfh the W65C80? even though 
a flank Address is not muHiptened on me Oaia Bus 

PHK. PH3;PLB 
The following instructions have "limited: use in Ihe Emulation mode 

• The hep ana SEP instructions cannot mooily ineMandX curs whe-.:,n 
I he Emulation mode in this mode the W and* Bits wilt always t» nigh 
(tope 1 1 

• When m iha Emulation -non ' I mwn instructions use the 

i • index Registers lor ihe memory address Also, tne MVP and 
MVN n«ru>Ctl0n»eaf1 only moire data wilhm the memory range 0000 
{Source Bank) to OOFF lOestination Bank) tor the W65C*ib, and OOCO 
id DDFf 1or Ihe W66C60S 

Indirect Jumps 

The JMP tai a^id JML la) instiucliorvs use ine direct Bank lor indirect 
addressing, wh-le JMP |a.x| and JSR |a \) use 1he Program Ban* lor in- 
dued address tables 

Switching Modes 

Wnen switching from the Native mode to the Emulation mode, the X and 
M oils of ine Status Regular are ad high (logic 1 ). the high byte of in* 
Slack is set lo 1 and the hi gfi bytes ol The X ar>d V Index aeg«sler S arp 
set to 00 To save previous values, theae byles must always be stored 
before cnangi ng moons Note I hat ihe low byte ol Ihe S. X and V Registers 
and I ne to w ana nigh oyte ol the Accumut atoi (A and Blare not aMecieo 
by a mode change 

HOW Hardware Interrupts. flHK, and COP Instructions Allecl 
the Program Bank and the Data Bank Registers 

When >n the Native mode, the Program Bank regisier |PBRi is clearcdio 

00 when a Hardware interrupt, 8RK or COP it executed in the Native 

mode, preu>ous PBR contents rs automai.caiiy saved on Stack 

In the Emulation mode, the PBR and OBH registers areclearedioOOwnen 

a hardware interrupt, BHKor COP isexecuted in this case, previouscon- 

tenls of me PBR are not automatically saved 

Note that » Return tr om Inlerrupl (RTt) should always. be e.ec uterj Irom 

ine same "mode which originally generated the interrupt 

Binary Mode 

The Binary mode is set whenever a hardware or software interrupt ■ 

executed The O Hag wiihm the Status Register is cleaied to zero 

WAI Instruction 

The WAI instruction pull * RD V low and placea the processor in the WAI 
lowpower'mode NMI. IRQ or RESET w.l. lermmateineWAI c ondition 
and trarvslarconUotto the inlerrupl handler rou1>ne Note thai an ABORT 
input will abort me WAI msuuciion, b ut w ill not restart Ihe processor 
When the Status Reg-alar I Mag is »ei <iSo" d.sabled r , Ihe ITO intarrupf 
will cause the nen.1 instruction iroilr/wing tne WAI aiatniCMAj to be 
eiacuted witnoul going to she IRQ interrupt n&ndiei Tnia method re- 
sults m me highest speed response lo an IRQ input When an interrupt 
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is rectiw.d a «ei *n S15HTwhicrt occufs ounns me W.-. 

processo r «■ M rn | Ine WAl .nsiruChon Oihei than RT5 4 highest 

P»ionly|, ABORT 15 me neil highest priority, lollowed By NMI nr IRQ 
interrupts 

STP Instruction 

Tn«STP-nstiuchondpsatHBsfh«*2cloch>oaiH:»rcuiir^ w^ndiijhnd 
1 he *2 clock n halo . n I he high stale In mi* case ine O ata Bui * 
in the date trailer sraiir and me Bank address w.11 not be mui|ipieiu*d 
oniothn Data Bus Upon executing me STP .nstrudw, LheHRsional is 
the only mpu! wmcli can restart trie processor The procstwt is restarted 
by cruising irre «? C "oc* wnicn occ uiitnvv fail, ng * doe of in* RES 

input Noietrka£!hee ? iefn«lasaira,iofmu*lt»8laWean<lcipwal.na5W(M- 
eilybefoie RES goes high *k«v 

COP Signature* 

Signatures- OO-TF may be user defined, while signature. 8i.i-n j , ri- 
ser «*d ionnsiruciions on ludjrem.croprocessors |i • WtfrCaiai Con- 
jact WOC lot soiiwate ^nuiation ol fu^re microprocessor h*tay, 4 ,e 
functions 

WDM Opcode Use 

M upcode M.111 be used on fuiu re microprocessors f o. c^rr.n.* 
me new W65C832 uses mi, opcoo* to prov.de 33- b-t Uoal.ng.pa.nl and 
other 32-dh mam arvd data operai.ons Note mat the W65GB32 will be it 
piug-tn-plgy replacement lor Ift. W&iCa J6, and can be u*ed wnwB hlgh . 

speed. 3J-Dit math processing* reqwed Th«W65Ca3? «.m be 
■n the near fuiuro 

HDY Pulled During Wnl* 

7jl*""°SM02do«nolBlopdoi'inQBwtiiaoipiifatiCHi. In contrast both 
ISI^E? 02 and |h0 W6SC 8 1 * *) slop dur.ng write operations Tho 
W85C802 step* dur.ng a write when .r> me Naliv* mode Cui does noi 
slop whe-i m tho tmulaiaon .mode 



MVN and MVP Affects on the Dale Bank Register 

Trve mvn ana MVP instructions change ma Data Bank Register to m* 
value a' me second byle of the instruction wssi.nation bank addr«ss| 

Interrupt Prtorilies 

r»e luiiowing mlefiupt priorities will oe in ertect should mure Ihan one 
— upl occul al ItHTHmt n-ne 

Highest Priority 




Lowest Priority 

Transfers Kom 6-Blt lo 16- Bit, 01 16- BM lo S-Bll Register* 
am. in r.Jrirs rrom one register to another will result <n a lull 18-bit output 
Iram the source register TnedesrmationregistersiHJw.il delermineiho 
dumber or bits actually snared m me dest.nai.on register and ine value* 
stored m the processor status Register The loltewmg are always 1fl-oi1 
transfers regardless »i rhe accumulator size 

TCS. TSC, TCD, TDC 

Slock Tramters 

Whon m the Emul*i ion moo, *Q! is forced into SH fnih.scas* tneB 
Accumulate/ will nor De loaded into SH during a TCS instruction When 
m me Native m.00* me 8 Accumulator * transferred lo SH. Note mat In 
Dotn ineEmulanoAwd Native modes me lull 16 bifaol the Stack fieais- 
ter are transter.ed to jh« A, B and C Accumulators, regardless of the 
state of trw M Bit m the Status Register. 



WOC Toolbox System- Emulator 
Features 

• Heat-Time emulation ol the lrV$SC80.2/aie«nd me WB5C02 

• Uses an 1 ne.pensive Apple 1 le Computer as h M r [softwof « prmidodl 

• UK bytes of Emulatron RAM. mappanif n^Kfjiamj 
» Optional RAM enpansion to ?5«K 

• Ootionar hardware Real. Time Trace Board 

• Oj:.|.,;nalB02/ai6 Emulation Pod Unit 
■ Singla-Slep 

• *B bit trace memory of up to 20*8 m»chi ne cycles 

• Three 40-bit Otaak point control registers providing. 
— Break on Address 

— Break on Da1a 
-Break on Control 
—Break on User Status 
—Break on Nth Occurane* 
—Coast Made 

• Microsecond 1 execution timet 

• Also available ,n In-Orcurt- EirtUuat.gr. chip or system test conjuration 

P roducl Overvia w 

Tri* Toolbox Sysiem-EmuUtor consists ot a Mam Unit ana interface Card 
that plugs in la one of the Apple Computer 5 expansion slots The Ma.n 
Un-t proves «i| necessary log.c tot breakpointiitg. smgte-slepp.ng arvd 
mapping In th.s conliguration the us*r may paHorm basic debug opera- 
tions or use th« Tooibo» in me Eual uanon Mode 
W'ir» the opi.or%Bi Peat-Time Trace Board, the user now nas *D bits of 
trace memory wimm a window ol SJOsfl machine cycles A optional 
tmuiat.on RAM Expansion Board .saiso available which mcreasss me 
users emu4al>on RAW by 64K bytes or 256K byt«. with memory conngur. 
ahon under software conlroi 

Tne-roolboit may be used with or without «h« optional Pod Un.i With ine 
Pod Unit me use. can plug into the prMoiype m*ropr«e»rx socket for 
hardware debug Since the Mam Ural remains the same regardless rM 
the microprocessor used, me user does nol have to »earn a new set ol 
Tooi&oi commar»da roreach type ot proc*ssor 
Apple He is a trademark ot Apple Compute*, ine 



AddltlonaJ information 

For additional .formation on the W65CS02ei6, refer to me following 

publucal'Ons 



ProgrimfnlnB lh « 65816 
William Labiak 
SV0EX Inc. 
2344 Sixth 8t 

Berkeley, CAgi?fa 

The 6MI, S4C02 and 65816 Handbook 
Sieve Hencjrn 
Wrebei Systems, ine 
8*37 Mayfield Rd 
Cnesreriand OH **026 

65616. SSMS Assamoly Language Prog itmml ng 
Michael Fisher 
Oaborna McGraw-MiU 
2600 Tenm Si 
BorHeiey. ca gario 

Progrimmlng the 65116 Including |h« S502. 6SC02. and 65M2 

David Eyes and Ron Lieiyy 

"'entice rial I Press 

A Division of Simon a Schuster, Ine 

Quit & Wester n Sldg 

One Gull a Western Plata 

New York. NT 10033 
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Packaging Information 
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Ordering Information 



P iJ C ripBo n 
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APPENDIX 3 



The Apple IIgs 
Tool Sets 



Approximately half of the Apple II(.s tool sets are located in ROM. (They are marked 
with asterisks in the table below.) When ProDOS 16 starts up, it installs RAM- 
based bug fixes and enhancements to the ROM -based tool sets by executing the 
TOOL. SETUP program in the SYSTEM/SYSTEM. SETUP/ subdirectory of the boot 
volume. 

RAM-based tool sets are stored on disk in files with names of the form TOOLxxx 
(where XXX represents the three-digit tool set number in decimal form) in the 
SYSTEM/TOOLS/ subdirectory of the boot volume. You can install these tool sets 
from inside an application with the Tool Locator's LoadTools and LoadOneTool 
functions (see chapter 3). 

The macro files referred to in the following table contain the macro definitions 
for tool set functions in assembly language form. These files are included with the 
Apple lies Programmers Workshop (APW). 



1 il/lo of Apple 


[ICS Tool Sets 




Toot Set 






Number 


Too! Set Same 


APW Macro File 


001 


*Tool Locator 


M 16, LOCATOR 


002 


;i N 1 1 'inory Manager 


M 16. MEMORY 


003 


♦Miscellaneous Tool Set 


M16.MISCTOOL 


004 


♦QuickDraw 11 


M16. QUICKDRAW 


005 


•Desk Manager 


M 16. DESK 


006 


* Event Manager 


M 16. EVENT 


007 


* Scheduler 


M16. SCHEDULER 
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roof Set 








Number 


Tool Set Name 




APW Macro File 


008 


♦ Sound Manager 




Mia SOUND 


009 


♦DeskTop Bus Tool Set 




M16.ADB 


010 


•Floating-Point Numerics 


(SANE) 


M 16. SANE 


on 


♦Integer Math Tool Set 




M16.INTMATH 


012 


♦Text Tool Set 




M16.TEXTTOOL 


013 


*RAM Disk Tool Set 




[internal use] 


014 


Window Manager 




M 16. WIN DOW 


015 


Menu Manager 




M 16. MENU 


016 


Contra! Manager 




M 16. CONTROL 


017 


System Loader 




M 16. LOADER 


018 


QuickDraw Auxiliary Tool Set 


M16.QDAUX 


019 


Print Manager 




M16. PRINT 


020 


LineEdit 




ML6.LINEEDIT 


021 


Dialog Manager 




M 16. DIALOG 


022 


Scrap Manager 




M16. SCRAP 


023 


Standard File Operations 


Tool Set 


M16.STDFILE 


024 


Disk Utilities 




[none] 


025 


Note S\ nthesi/.er 




M16.NOTESYN 


026 


Note Sequencer 




[none] 


027 


Font Manager 




M 16. FONT 


028 


List Manager 




M16.LIST 


* ■ tool set in R 


OM 
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APPENDIX 4 



Number- 
Conversion 
Functions 



The Integer Math Tool .Set (tool set III includes nine functions you can use to 
convert numeric data from one numbering system to another. (See the table below.) 
The three numbering systems supported are binary, decimal, and hexadecimal. The 
purpose of this appendix is ten explain how to use these conversion functions in your 
programs. 

Table of Integer Math Tool Set Number-Conversion Functions 

Fu n ction Description 

Int211ex Converts unsigned integer to hex ASCII string 

Loug2Hex Converts unsigned long integer to hex ASCII string 

Hcxlt Converts unsigned integer to hex ASCII string on stack 

Hex2Int Converts hex ASCII string to unsigned integer 

Hex2Long Converts hex ASCII string to unsigned long integer 

lnt2Dee Converts signed/unsigned integer to decimal ASCII string 

Long2Dec Converts signed/unsigned long integer to decimal ASCII string 

Dec2Int Converts signed/unsigned decimal ASCII string to integer 

Dec2Long Converts signed/unsigned decimal ASCII string to long integer 
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BINARY TO HEXADECIMAL 

There are three functions for converting unsigned binary numbers to hexadecimal 
form: Iut2Hex, Long2Hex, and Hexlt. 

inl2Hex eon verts a 16-bit unsigned binary integer to an ASCII string representing 
its value in hexadecimal form. Here is how to use ft: 

PushWord TheNumber ; Number to convert 

PushPtr HexString -,Push pointer to hex string 

PushWord #4 '.Length of hex string 

_Jnt2Hex 

RTS 

HexString DS 4 -.(standard ASCII; bit 7 = 0) 

The hexadecimal string returned by tnt2Hex is right-justified and padded on the 
left with ASCII characters. In most situations, you will reserve lour bytes for the 
string because the maximum value of a 16-bit integer is $FFFF. If you do not leave 
enough room, an error of $0B(M (string overflow) will be returned. 

You can also use Hexlt to convert a 16-bit unsigned integer to a 4-byte ASCII 
string of hexadecimal characters. The difference between it and Int2Hex is that the 
result is returned on the slack: 

PHA ;Space for result (Lonq) 

PHA 

PushWord TheNumber ; Number to convert 

_HexIt 

PopLong HexResult ;Pop the result 

I In- first bytes popped from the stack are the low-order hexadecimal digits. 

Long2Hes works much like Int2Hex. The key difference is thai the number to 
be converted is a 32-bit unsigned long intej 

PushLong TheNumber ;Push number to convert 

PushPtr HexString jPush pointer to hex string 

PushWord #8 ;Length of hex string 

_Long2Hex 
RTS 

HexString DS 8 ;(standard ASCII; bit 7=0) 

Notice thai eight bytes arc reserved for the hexadecimal string result because the 
maximum value for a long integer is $FFFFFFFF. 
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HEXADECIMAL TO BINARY 

To convert ASCII strings representing hexadecimal numbers to binary form, use 
Hex2Int (integers) or Ile\2Long (long integers). In both cases, the binary result is 
returned on the stack. Here is how to call Hexilnt: 

PHA '.apace for result 

PushPtr HexNumber ;Pointer to hex number 

PushWord iM ^Length of hex number string 

_Hex2Int 

PopWord BinResult >P°P tne result 

HexNumber DC C7EAF' .Number to convert 

The length parameter cannot he greater than A since an integer cannot exceed 

■SFFFF. 

Hex2Long converts hexadecimal strings to 32-bit numbers: 

PHA i space for result 

PHA 

PushPtr HexNumber {Pointer to hex number 

PushWord #8 -.Length of hex string 

_Hex2Lpng 

PopLong BinResult ;pop the result 

HexNumber DC C • 00E1 2000 ■ '.Number to convert 

The length parameter cannot be greater than 8 for long integers. 

BINARY TO DECIMAL 

The binary-to-decimal conversion functions are useful for transforming binary num- 
bers to the m ore -recognizable decimal form. 

Int2DeC converts a 16-bit signed or unsigned binary number to an ASCII String 
representing the number in decimal form. If the number is negative, the string 
contains a minus sign to the left of the first digit in the string, No plus sign is 
inserted if the number is positive, however. 

Here is the calling sequence for Int2Dec: 

PushWord TheNumber ;The number to convert 

PushPtr DecString -.Pointer to decimal result 

PushWord #6 .Size of string 

PushWord SignedFlag ; = unsigned, 1 = signed 

_Int2Dec 

RTS 

DecString DS 6 ;ASCII decimal string 
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The value of the SignedFlap parameter indicates whether the number is to be 
considered signed or unsigned. The size of the string should be at least 6 to 
accommodate the longest result. The result is right-justified and padded on the lefl 
with blanks Each character of the result has the high-order hit cleared to 0. 
Long2Dee works much as Int2Dec does: 



PushLong Thehlumber 
PushPtr DecString 
PushWord #T1 
PushWord SignrdFlag 
_lnt2Dec 
RTS 



The number to convert 
Pointer to decimal reault 
Size of string 
= unsigned, 1 = signed 



DecStnng DS 



11 



;ASC; 



decimal string 



The key differences between this and Ent2Dec are that the number to be converted 
is a long word and thai the size of the string returned might be up to eleven 
characters long. 

DECIMAL TO BINARY 

Most programs ask users to enter numeric information in decimal form. To convert 
decimal numbers to the binary form the 65816 understands, use Dec2Int or 
Dec2Long. 

Dec2Inl converts the ASCII string for a decimal number to a 16-bit unsigned or 
signed binary Dumber: 



PHA 

PushPtr DecString 

PushWord #G 
PushWord 5tgnedFlag 
_Dec21nt 
PopWord BinWord 
RTS 



DecString DC C 3342 ' 



; space for reault 

;Pointer to decimal string 

; Size of string 

;0 = unsigned, T = signed 

;get the result 



iNumber to convert 



Notice that Dec2Int returns the 16-bit binary result on the stack. 

Dee2Long converts the ASCII strum for a decimal number to a 32-bit unsigned 
or signed decimal number: 



PHA 
PHA 
PushPtr DecString 

PushWord #1 1 
PushWord SignedFlag 



;space for reault 

Pointer to decimal string 

Size of s t r ing 

= unsigned, 1 = signed 
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_Dec 2 Long 

PopLong BinLong ;get the result 

RTS 

DecString DC C ' -21 B82423323 ' ^Number to convert 

Dec2Long returns the 32-bit result on the stack. 

For both Dec2Int and Dec2Long, SignedFlag is a Boolean indicating whether 
the number is unsigned (0) or signed (nonzero). 
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APPENDIX 5 



ProDOS File 
Type Codes 



The table below indicates the general contents of a file with a given ProDOS file 
type code, The standard three-character mnemonics arc usually shown only when 
you catalog the disk under ProDOS 8 or APW. Even then, some of the mnemonics, 
particularly the ones lor Apple HI SOS files, are not used; instead, the hexadecimal 
file type code is displayed to identity the file type- 
Table of ProDOS File Type Codes 



Fife Type 


Standard 




Code 


Mnemonic 


Description of File 


$00 




Uncategorized file 


$01 


BAD 


Bad block file 


$02 


PCD 


Pascal code (SOS) 


$03 


PTX 


Pascal text (SOS) 


$04 


TXT 


ASCII text file 


$05 


PDA 


Pascal data (SOS) 


$06 


BIN 


Genera] binary file 


SOT 


FXT 


Font file (SOS 


Sil.S 


FOT 


Graphics screen file 


SOU 


BA3 


Business BASIC program i.SOS'i 


SUA 


DA3 


Business BASIC data (SOS) 


SOB 


VVPF 


Word processor file (SOS; 
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File 


Type 


Standard 




Code 


Mnemonic 


Description of File 


$0C 




SOS 


SOS system file 


$OEMOE 




[Reserved for SOS] 


SOF 




DIR 


Subdirectory file 


$10 




RPD 


Record Processing System dala (SOS) 


Sll 




RPF 


Record Processing System Index (SOS) 


$12 






AppleFile discard file (SOS) 


$13 






AppleFile model file (SOS) 


$14 






AppleFile report format file (SOS) 


$15 






Screen library file (SOS) 


S16-$18 




[Reserved for SOS] 


$19 




ADB 


AppleWorks database file 


$1A 




AWP 


AppleWorks word processing file 


$]B 




ASP 


AppleWorks spreadsheet file 


$JC- 


|AF 




[Reserved] 


8 BO 




SRC 


APW source code 


SB! 




OBJ 


APW object code 


$B2 




LIB 


APW library 


$B3 




Slfi 


Pro DOS 16 system program 


$B4 




RTL 


APW run-time library 


$B5 




EXE 


APW executable shell application 


$B6 




STR 


ProDOS 16 permanent in it (start-up) file 


$B7 




TSF 


ProDOS 16 tempoiai\ in it file 


SBS 




NDA 


New desk accessory 


SB9 




CDA 


Classic desk accessory 


$BA 




TOL 


Toot set 


$BB 




DRV 


ProDOS 16 device driver 


SBC-SBE 




[Reserved for ProDOS 16 load files J 
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File Type 


Standard 




Code 


Mnemonic 


Description qj Fife 


$BF 


DOC 


ProDOS 16 document file 


$C0 


PNT 


Compressed super high-res picture file 


$Cl 


PIC 


Super high-res picture file 


$C2-$C7 




[Reserved] 


$C8 


FON 


ProDOS 16 font file 


SC9-SEE 




[Reserved] 


$EF 


PAS 


Pascal area on a partitioned disk 


$F0 


CVID 


ProDOS H added command file 


$F1-$F8 




ProDOS 8 user-defined files 


$F9 


P16 


ProDOS 16 file 


$FA 


[XT 


Integer BASIC program 


$FB 


IVB 


Integer BASIC variables 


$FC 


BAS 


Applesoft BASIC program 


$FD 


VAR 


Applesoft BASIC variables 


$FE 


REL 


EDASM relocatable code file 


$FF 


SYS 


ProDOS 8 system program 


NOTE: SOS stands 


For the Apple III Sophisticated, Operating System. 
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APPENDIX 6 



Memory Cards 
for the Apple Hgs 



A standard cs comes with 256K of RAM, twice the memory capacity of either the 
lie or lie. This configuration is perfectly fine for running lie/ Ik-style programs. It 
is not enough, however, to run the new cs applications that use the Macintosh-like 
desktop environment provided by the ess software tool sets, This is because these 
types of programs typically need plenty of memory to hold RAM -based tool sets, 
custom fonts, desk accessories, and so on. 

For some applications, you may not need more memory, but the application will 
perform much better if you do have it. The best example is version 2.0 of 
AppleWorks. It uses extra memory to increase its desktop space so that you can 
have several lar^e files open at the same tone, 

You may also want to add extra memory to take advantage of useful utility 
programs that make the <-s taster and more pleasurable to use. Here are some of 
the things for which extra memory can be used: 



• A RAM disk 

• A disk-caching area 

• A print-spooling area 

• A butter area for copying disks in fewer passes 



RAM disk support for extra memory is a built-in feature on the cs, Using the 
Control Panels RAM Disk command, you can allocate as much available memory 
as you like for use as a RAM disk, 

This appendix reviews available memory cards for the cs that plug into the cs s 
memory expansion slot. See the list of manufacturers below. RAM memory on a 
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card in this slot forms part of the 65816 address space, so programs can use it. just 
as they would use the 256k memory core. The permitted memory limit for such 

cards is S megabytes. 

MANUFACTURERS OF MEMORY CARDS FOR THE GS 



OctoRAM 
MDIdeas, Inc. 
1 1 63 Triton Drive 
Foster City, CA 94404 

415/573-0580 

Ram Pale 4gs 
( Jrange Micro, Inc. 
1400 N. Lakeview Ave. 
Anaheim, GA 92807 

714/779-2772 



Apple lies Memory Expansion 
Card 

Apple Computer, Inc. 
20525 Mariani Avenue 
Cupertino, CA 9501 I 
408/996-1010 

cs RAM and cs RAM Plus 
Applied Engineering 
P.O. Box 798 
Carrollton. TX 75006 
214/241-6060 

RamStakPlus 
AST Research Inc. 
2121 Alton Avenue 
Irvine. C A 927 14-4992 
714/553-0340 

APPLE 1IGS MEMORY EXPANSION CARD 

The first memory card available for the GS was Apples own Apple llr.s Memory 
Expansion Card. It comes with 256K of RAM, hut you can expand it to either 512K 
Or IM by adding one or three additional rows of eight 256Kxl bit memory chips to 
empty sockets on tlie card. { Apple does not recommend a 76ok configuration because 
some programs cannot handle it.) These chips arc inexpensive. 

The Apple card is definite!) a "plain-vanilla" product. It comes with no software. 
not even a RAM diagnostic program for testing lor bad memory chips. In addition, 
it cannot be expanded past IM and sou cannot add any ROM to it. Despite this, it 
is an attractive card because of its low price and its excellent owners guide. The 
owners guide clearly illustrates how to install the card and add memory to it. and 
it contains a useful chapter describing how to allocate memory on the card for use 
as a RAM disk, 

APPLIED ENGINEERING GS RAM 

Applied Engineering is a welt-known manufacturer of RAM tank for Apple II 
computers. Its two main products, Ram Factor and (for the lie only! 1 RamWorks, 
have sold in ihe tens of thousands 
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Applied Engineering actually has two such cards: DS RAM and cs RAM Plus. 
The GS HAM uses 256Kxl-bit HAM chips and ran hold up to 1.5M of memory. It 
is essentially the same as Apple's card hut with two extra rows ofeighl KAM sockets. 

GS HAM Phis looks very similar to GS RAM, hut it uses 1,02 IK* 1 hit (one- 
megabit) HAM chips. This means that each row on the card holds one megabyte of 
memory, so the capacity of the card is six megabytes. A set ol eight of these chips 
is still more expensive than the 256 Kxl chips, hut the cosl is dropping fast 

Both cards contain an expansion port that Applied Engineering plans to use for 
adding 2M more RAM. or ROM, via a piggyback card. 

gs RAM and GS RAM Plus come with diagnostic software and the AppleWorks 
2 Expander program. The Expander enh \pple Works 2.0 so that it will work 

even better than it already does with gs memory cards. The special enhancements 
it oilers are us follow s; 

• More lines in the word processor (22,600 versus 7250) 

• More records in the database (22,600 versus 63.50) 

• More lines in the word processor and database clipboard 
(2,042 versus 250) 

• Display of the current time Oil the screen 

• Saving large files to multiple disks 

• Up to a 64K print butter (versus 2K.) 

• Quick time entry in the database 

MDIDEAS OCTORAM 

The MDIdcas OetoRAM is an interesting memory card. It contains eight standard 
SIMM (Single In-line Memory Module) sockets that can hold 256K memory modules 
or 1M memory modules. Thus, the capacity of the card is either 2M (eight 256K 
SIMMs' or BM eight LM SIMMs; 

A SIMM is a small printed circuit card that has eight memory chips soldered to 
it. To add it to the memory card, you simply clip it into a socket on the card. SIMMs 
are new to the Apple II world, but they are being used by Apple on the Macintosh 
Plus. The Macintosh Plus has four SIMM sockets to which you can add 256K SIMMs 
(1M total) or 1M SIMMs (4M total:. 

The 1M SIMMs are currently a bit more expensive than conventional memory 
chips, and they are more difficult to find because they are made by fewer manufac- 
turers. It is expected that they will drop in price, hut at a slower rate than the 
l,024Kxl RAM chips. 
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ORANGE MICRO RAMPAK 4GS 

Orange Micro's memor) card is called the RamPak les, As its name suggests, its 
maximum capacity is 4M. It is the only memory card thai uses 256Kx4-bit memory 
chips, which means that you can increase memory by 256K by adding only two 
chips. This makes the board less crowded than cards that use 256Kxl RAM chips 
(eight 256Kxl chips are needed for 256K). Two 256 Kx4 chips are still more expensive 
than eight 256foc] chips, however, because 256Kx4 chips are a nonstandard size 
Tlic> are also more difficult to find. 

RamPak comes with a Memory Management Utilities disk that contains a useful 
and easy-to-use program that performs the following tasks: 

• Memory verification 

• Reporting of disk-access statistics 

• Disk caching 

This program installs itself as a Classic Desk Accessory (such as the Control Panel), 
so you can call it up at any time by pressing Control-Open Apple- Esc from the 
keyboard. 

The most interesting aspect of the RamPak software is its ability to enable disk 
caching for any disk device used with ProDOS. Caching is the storing of disk blocks 
in memory so that when a read operation occurs, the block can be retrieved quickly 
from memory rather than from the relatively slow, mechanical drive. If most of the 
disk is cached, file operations are sped up dramatically. 

The main advantage of caching over using a RAM disk is that there is no danger 
of losing data because only read operations are cached. Data is always transferred 
to the disk when a write occurs. Another advantage is that you do not have to 
transfer files to the cache explicitly: that is done transparently by the caching software 
the first time you load a program into memory, 

The RamPak software is able to use up to 3.5M as a cache buffer. You can either 
tell the software how much memory to use as a Cache or tell it to allocate memory 
dynamically, 

AST RESEARCH RAMSTAKPLUS 

The AST RamStakPlus is interesting because it is the only memory card that contains 
sockets for ROM, its maximum RAM capacity is 1M (four rows of eight 256Kxl bit 
chips), the same as Apple's card. It is too bad that it was not designed to hold more 
RAM, but it would be difficult to do because the ROM sockets take up a lot of 

board space. 

The RamStakPlus has four ROM sockets, each of which can hold a 8K-64K 
EPROM (Erasable Programmable ROM) or a 2K-32K EEPROM (Electrically Eras- 
able Programmable ROM). You will probabl) want to use EEPROM because you 
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can erase it and program it simply by running a program. You need a special 
programming device to program an El'ROM. 

The RamStakPlus comes with a utility program that performs diagnostics and 
programs EEPROMs. Programming an EEPROM is simple; all you have to do is 
put all the files you want to place in the EEPROM in a subdirectory, then run the 
EEPROM programming program that AST supplies. 

In keeping with Apple's standard guidelines, the files in ROM are organized in 
the same way they are on a disk, so you will have created a ROM disk. If the ROM 
contains the necessary operating system programs, you can even boot from ROM 
by setting the Startup Slot in the Control Panel to ROM Disk. The big difference 
between a ROM disk and a RAM disk is. of course, that the ROM disk does not 
disappear when you turn off the GS. 

MAKING A CHOICE 

With this analysis of GS memory cards by your side, yon should he able to choose 
a card that will suit your present and future memory needs. To summarize, the key 
factors in deciding what card to buy are: 

• The base price ol the card 

■ The cost of adding more memory 

• The ease of adding more memory 

• The upper RAM limit 

■ The ability to ileal with ROM 

■ The availability ol software utilities 



Table Aft summarizes the features of each nienion card. 

If you have a limited budget, keep in mind that you can start with just a little 
RAM and add more when prices drop (or when you desperately need more). (You 
can buy RAM chips at electronics parts stores and mail-order warehouses.) At this 
stage, you will have to determine what types ol RAM chips to buy and where to 
install them on the card. 

RAM chips are produced by various manufacturers to many different specifica- 
tions, so you must be careful tu choose the right ones for your card. For c;s cards, 
you need RAM with a speed specification of 150 nanoseconds or faster that uses the 
"CAS before HAS" refreshing technique. The capacity and configuration of the RAM 
chips is also important; the possible choices are; 
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Table A6: Apple llc;s Memory Cards: A Comparison Chart 



Product 


Memory 

Ra, 


Minimum 
Increment 


RAM Chip 

Size 


ROM 

Capability 


Utility 

Softunrr 


litis Memory 
Expansion Card 


256K-1M 


256K 


256K* I 


None 


None 


gs RAM 


236K-1.5M 


256K 


256Kxl 


Option 


Diagnostics 


GS HAM Plus 


JM-fiM 


IM 


l.024Kxl 


Option 


AppleWorks 
Enhancements 


RarnStak Plus 


256K-1M 


256K 


256KxI 


On card 


Diagnostics 

ROM programmer 


OctoRAM 


256K-2M 
1M-8M 


256K 
IM 


256K SIMM 
IM SIMM 


Option 


1 diagnostics 


RamPak 4GS 


512K-IM 


256K 


256K*4 


None 


Diagnostics 

Caching 

Statistics 



• 256Kxl-bit (8 chips = 256K) 

• l,024Kxi-bit (8 chips = IM) 

• 256Kx4-bit (2 chips - 256K) 

• 256K SIMM 

• IM SIMM 

Consult your card's manual to determine what kind of RAM chip the card requires 
and how man} chips you need (eighl for 256KxI or l,024Kxl; two For 256Kx4. or 
one SIM Mi If you want to play it safe, order the RAM chips directly from the 
card's manufacturer. You will probably pay a little more, hut you will not have Ml} 
headaches. 

The order in which you fill rows of empty RAM sockets on a card is also Important 
If you do not fill the sockets in the proper order, the card will not work properly. 
Again, consult your card's manual for installation instructions, 
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APPENDIX 7 



Disk Drives for 
the Apple IIgs 



There are nine different Apple-brand, removable-media disk drives you can use 
with the Apple lies: five S'/i-inch drives and four 3V&-inch drives. This appendix 
looks at each of them and examines how to use them with the < s. 

5'/*-INCH DISK DRIVES 

The original drive for the Apple H was the Disk II, first released in 1979, It works 
with 140K 5 '/i-inch floppy disks and comes with a permanent cable that terminates 
in a 20-pin rectangular connector. 

Apple no longer manufactures the Disk II, but the company has four other 544- 
inch drives to replace it: the UniDisk 5. 25, the Apple 5.25 Drive, the Disk lie, and 
the DuoDisk. (The Apple 5.25 Drive is the same as the UniDisk 5,25 except lor its 
cs-like platinum color.) The drive mechanism in each ol these drives is functionally 
equivalent to that of the Disk II, so all of Apple's 5 l A-iuch drives read and write 
the same disks. 

The DuoDisk is unique in that it contains two drives in one box. The UniDisk 
5.25, Apple 5,25 Drive, and Disk He are all one-drive devices. Each of these drives 
has the same type oi connector cable, however — one that terminates in a D-shaped, 
19-pin, male DB-19 connector. 

You can connect two (but no more than two) UniDisk 5.25 or Apple 5.25 drives 
together by attaching the second drive to a connector on the back of the first drive. 
This method of connecting multiple drives is called daisy-chaining and is Apple's 
"official" technique for attaching multiple drives to a system. Because a DuoDisk 
contains two drives, it does not have a daisy-chain connector; nor do the older Disk 
II or Disk He drives. 
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T-IM H DISK DRIVES 

In 1985, Apple started sellings Rife-inch drive for ihe Apple M called ihe UniDisk 
3.5. This is a very intelligenl device, containing a 65C02 microprocessor and a 
program in ROM for controlling disk data transfers. It uses double-sided 800K hard- 
shelled disks lor media and works with any Apple II model (except older Apple lie 
systems! The UniDisk 3.5 cable has the same DB-19 connector as the cable for the 
UniDisk 5.25 and the DunDi.sk. 

When the gs was announced in September 1986, another 3Vi-inch drive was 
unveiled, the Apple 3.5 Drive. It works with the same BOOK disks as the UniDisk 
3.5 but docs not have the built-in intelligence of the UniDisk 3,5. It works only 
with the gs or the Macintosh. The main advantage of using an Apple 3,5 Drive 
instead of a UniDisk 3.5 on the gs is that the Apple 3.5 Drive operates slightly 
faster. 

The other two Apple- brand 3'/>inch drives that can be made to work with the 
CS are the standard 400K and 800 K external drives for the Macintosh. To use them, 
you must have a Universal Disk Controller (UDC) from Central Point Software 
(9700 S.W. Capitol Hwy M #100, Portland, OR, 97219 [503/244-5782J ); more infor- 
mation on the UDC is provided below. The UDC also works with all other Apple 
drives (except the DuoDisk) and with one non-Apple-brand 3%-iiich drive, the. BOOK 
Chinon 3.5 drive sold by Central Point Software, 

USING DRIVES WITH THE APPLE lies 

The cs has slots like those on the He and built-in peripheral ports like those on the 
lie, To select whether a port or its corresponding slot is active, use the Slots 
command in the Control Panel desk accessory. You can call up the desk accessory 
menu at any time by pressing Control-OpenApple-ESC, 

One of the built-in ports, corresponding to slot 5, is a disk drive port called 
SmartPort; it is designed to handle 3^-inch disk drives and any intelligent periph- 
erals that use the data-exchange protocol and electrical specifications defined by 
SmartPort. The SmartPort connector is a DB-19 type and is located at the back of 
the cs. 

Another built-in port, corresponding to slot 6, is the SWinch Drive Port. It 
shares the same physical connector as SmartPort — this does not cause problems 
because 5 ] /i-mch drives can be daisy-chained to SmartPort devices. 

You will probably want to daisy-chain drives to the SmartPort instead of using 
plug-in controller cards. Five types of drives can be chained to the SmartPort: the 
UniDisk 3.5. the UniDisk 5 .23. the Apple 5.25 Drive, the DuoDisk, and the Apple 
3.5 Drive. (You can also use the Disk II. but only if you have a special adapter cable 
made up.) It is important to understand, however, that you cannot chain these 
drives in just any order. 
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If you are using Apple 3.5 Drives, they must appear at the beginning ul the 
chain, before any UiiiDisk 3.5 drives or 5V4-inch drives. You can use up to two of 
these types of drives. 

At the cud of the chain conic the 5V4-incn drives; up hi two UniDisk 5.25 d 
or one DuoDisk (which is equivalent to two UniDisk 5.25 drives) may be used. 
There is one caveat relating to the DuoDisk, however — because of a hardware 
problem in the drive, you cannot daisy-chain a DuoDisk having a serial number 
below 433754. Apple has published a technical note describing a hardware fix to 
solve this problem, so track it down if you want to use an old DuoDisk with the GS< 

Between the Apple 3.5 Drives at the beginning of the chain and the UniDisk 
drives at the end of the chain come any UniDisk 3.5 drives. The number of 
UniDisk 3.5 drives is limited by the capacity of the OS power supply. Apple rec- 
ommends that vein have no more than four drives connected to the SmartPort 
(including any Apple .3.5 Drives and 5V4-inch drives;, although the gs seems tu be 
able to handle six quite well. 

Keep in mind that no other ordering of drives will work; the order must be Apple 
3,5 Drives followed by UniDisk 3.5 drives followed by 5 l /»-inch drives. 

The ProDOS 8 operating system requires that disk devices be mapped to tradi- 
tional slot/drive combinations with no more than two drives per slot. How, then, 
does it deal with the possibility that more than two drives may be chained to the 
slot 5 Smart Port? 

The way ProDOS 8 assigns slot/drive combinations to SmartPort disk drives is a 
bit unusual. In most situations, the first four 3Vk-inch drives are considered to be 
the slot 5/drive 1. slot 5/drive 2, slot 2/drive L, and slot 2/drive 2 devices. The two 
5 l /»-inch drives on the SmartPori correspond to slot 6/drive 1 and slot feVdrive 2. 
That is, connecting them to the end of the SmartPort chain is the same as connecting 
them to a controller card in dul fi- 
ll' you use the CS Control Panel to define a system RAM disk, however, the slol 
drive assignments are scrambled slightly. The first 3VS»-inch drive is still the slot 5/ 
1 device, but the RAM disk is assigned as the slot 5/drive 2 device. The next 
H£»i»ch drives "occupy" slot 2/drive 1 and slot 2/drive 2. Any other 3%-inch 
drives are not recognized by ProDOS 8. 

ProDOS 16, on the other hand, does not require slot/drive assignments and will 
work with any number of disk devices without difficulty. 

If you wish, you can also use either of the two standard Apple SVi-ineh disk 
controller cards on the cs. If you put the controller card in slot 5 or 6, keep in 
mind that vou will not he able to use the SmartPort or the Drive Port, respectively. 
You can also use Central Point Software's Universal Disk Controller on the GS, It 
works with almost any type of 5VSt-inch and 3 1 >inch drive available for the GS, 

The Chinon 3.5 drives the I DC works that are also sold by Central Point 
Software. The onl> major differences between them and Apple's 3Vfc-mch drives are 
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that they do not have daisy-chain connectors and that the disk eject button is 
completely mechanical, (There is an electronic disk eject mechanism that is con- 
trolled by the same software commands as the Apple 3V2-ineh drives ) The Chinon 
drives also work nicely as 800K external drives for the Macintosh. 

A nice Feature of the CS is that you can use the Control Panel to specify the slot 
of the drive from which to boot— this is called the Startup Slot. The default is "Scan, 
which means that the cjs will hoot From the first drive it encounters in a search 
beginning in slot 7 and moving down to slot 1 (this is the method used on the lie). 
Only the first drive in each slot or port is considered, however, so you cannot boot 
from a secondary drive. If you prefer, you can tell the GS to boot from a given slot- 
specify slot 5 to boot from the first .Wa-inch drive connected to the SmartPort, for 
example. 
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APPENDIX 8 



Resource 
Material 



If von arc interested it) developing software oo the GS you should become a member 
of APDA, the Apple Programmer's and Developer's Association. Its address and 
telephone number are as follows: 

Apple Programmer & and Developer a Association 
290 S.W, 43rd Street 
Reiilom WA 98055 
206/251-6548 

APDA is an association that was created by Apple Computer, Inc. in August 1986. 
It is administered by the Apple Pi i get Sound Program Libran Exchange Co-oper- 
ative Association {A.P.P.L.E. Co-op). The primary function of APDA is to dissem- 
inate prerelease versions of official Apple programming information for the Apple 
IT and Macintosh families of computers. This includes technical reference manuals, 
technical notes, ami software development tools. APDA is also a convenient source 
of non-Apple software and books for software developers. 

The advantage of joining APDA is that you can get your hands on useful technical 
information quickly, You do not have to wait for the information to be polished and 
published in final form. 

DEVELOPMENT SOFTWARE 

To develop software on the c;s. son will probablj want the Apple lk:s Programmer's 
Workshop (APW), which is available from APDA (see above). The basic APW 
package includes an editor. 65816 assembler, linker, and several support programs 
you can use to create programs that run under ProDOS 16. The official APW 
development system is almost identical to the ORCA/M system available From The 
Byte Works Inc., #207-4700 Irving Blvd. NW, Albmjuerque, NM, S71 II {505/898- 
8i83). This is because The Byte Works developed APW for Apple. 
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Another alternative r.s assembler, which does not require APW. is Merlin 816 
from Roger Wagner Publishing, Inc. (1050 Pioneer Way, Suite P El Cajon CA 
92020 [619/442-0522]). It conies with a linker which is capable of creating standard 
ProDOS 16 applications 

Apple also distributes an APW-coinpatiblo C compiler (developed by Megftmax, 
Inc.) which generates object code in the format expected by the APW "linker. 

An APW -compatible Pascal compiler is available from TML Systems (#23-4241 
Buvmeadows Road Jacksonville, FL, 32217 [904/636-8592],). TM L also sells a stand- 
alone Pascal compiler that uses the standard desktop environment of the c.s. 

MACINTOSH CROSS-COMPILERS 

You can also develop c.s applications using cross-compilers cm the Macintosh. The 
advantage ni doing this is primarily speed: compilation times are many times faster 
when performed by the Macintoshes 68000 microprocessor than when performed by 
the ess less powerful 65816. 

Cunsulair Corp. (140 Campo Drive, Portola Valley, CA, 94025 [415/851-3272]) 
sells the MACtoGS Assembler/Linker system. It assembles and links APW-compat- 
ible 65816 assembly language source code files on a Macintosh to create complete 
CS applications. Of course, to run tile applications, you must first transfer them to 
the c.s (using a communications program or Apple's Passport program). 

TML Systems (sec above) has a Pascal cross-compiler that generates a58 16 source 
code files that can then be processed by Consulair's MACtoGS Assembler/Linker. 
You can buy the compiler from TML separately or with the MACtoGS Assembler/ 
Linker included. Another Pascal cross-compiler is available from Megamax Inc 
(Box 851521, Richardsn,,, TX, 75085 [214/987-4931]). 

Megamax also has a ( : cross-compiler which works with the same source code as 
the version ofC it developed for APW does. 

REFERENCE BOOKS 

The many books von will find useful for teaching yourself how to program the c;s 
fall into four categories; 

• OS-specific books 

At the present time, most of these books have been written by Apple Com- 
puter, Inc. Those that are not yet in final form are available from APDA. 
When completed, most will be published and distributed by Addison -Wesley 
Publishing Company, Inc. 

* Books about the lie and lie 

These books will assist you in developing traditional applications on the GS. 
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• General books on programming in 65816 assembly language 

• Books about the Macintosh 

These books are useful because they describe general techniques For program- 
ming in a desktop environment. 



Books for the Apple lies 

Apple Computer. Inc., Apple lies Firmware Reference (Reading, MA: Addison- 
Wesley Publishing Company t9S7>. 

Apple Computer. Inc.. Apple lies Hardware Reference (Reading, MA: Addison- 
Wesley Publishing Company, L987). 

Apple Computer, Inc., Appk lies ProDOS 16 Reference (Reading. MA: Addi- 
SOQ-Wesley Publishing Company. Inc., 1987) 

Apple Computer, Inc. . Apple Has Toolbox Reference, volumes I and II (Read- 
Si A Addison-Wesley Publishing Company, 1988). 

Apple Computer, Inc., Apple Programmer's Workshop Assembler Reference 
(Cupertino, CA: Apple Computer, 1987), 

Apple Computer, Inc., Apple Programmers Workshop Reference (Cupertino. 
CA; Apple Computer, 1987). 

Apple Computer, Inc., Human Interface Guidelines (Reading, MA: Addison- 
Wesley, 1987). 

Apple Computer, Inc., Programmer's Introduction to the Apple lies (Reading, 
MA: Addison- Wesley Publishing Company, 1988). 

Apple Computer, Inc., Technical Introduction to the Apple tlGS (Reading. MA: 
Addison -Wesley Publishing Company, 1986) 

Fischer, Michael, The Apple lies Technical Reference (Berkeley, CA: Osborne 
McGraw-Hill, 1987) 

Wagner, Roger, Apple lies Machine Language for Beginners, (Greensboro, NC: 
Compute! Publications, 1987) 
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Books for the Apple lie and He 

Apple Computer, Inc.. Apple lie Technical Reference Mann- lj,„». MA; 

Addison-Wesley Publishing Company, 1985). 

Apple Computer. Inc., Apple lie Technical Reference Manual (Reading, MA: 
Addison-Wesley Publishing Company, |y«5i 

Apple Computer, Inc., Apple Numerics Manual (Reading, MA: Addison-Wesley 
Publishing Company, 198G 

Little, Gar) B . Apple ProDOS; Advanced Features for Programmers (Bowie, 
VI D Brad) Communications Company, 1985] 

Apple Computer, Inc., ProDOS Technical Reference Manual (Reading, MA: 
Addison-Wesley Publishing Company, 1965 

Utile, Gary B., Inside the Apple lie (Bowie, Ml): Br.uK Communications 
Company, 1985 . 

Little, Gary B., Inside the Apple lie (Bowie, MD: Brady Communications 
Company. 1985 

Books on 65810 Assembly Language Programming 

David, and Ron Uchty, Programming the 65816 Including the 6502 
65Cm and 65802 (New York: Prentice-Hall, 19S6). 

Fischer, Michael, 658W65802 Assembly Language Programming (Berkeley CA 
Osborne McGraw-Hill, L986). 



Books for the Macintosh 



Apple Computer, Inc., Inside Macintosh, volumes I. II, III. and [V (Reading, 
MA: Addison-Wesley Publishing Company, 1985, 1986). 

Chcrnieofl; Stephen. Macintosh Revealed: Unlocking the Toolbox andianapolis, 
IN: Harden Book Company, 1985 

ChcmicorT". Stephen. Macintosh Revealed: Programming with the Toolbox- (In 
dianapolis, IN: Hayden Book Company, 196 
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Little, Gary B Mac Assembly Language A Guide for Programmers (New York: 
Prentice-Hall, 1986). 

MAGAZINES 

Magazines are the best sou ret- of information on what software and hardware prod- 
ucts are currently available for the GS. Many of the magazines that are available are 
written for a general audience, but some are clearly lor programmers only The 
ones marked with an asterisk in the following list are the ones programmers will 
find most interesting 

A + 
1 1 Davis Drive, Belmont. CA 94002 

415/598-2290 

* Apple Assembly Line 
P.O. Box 2S03UU Dallas. TX 75228 
214/324-2050 

Call -A.P.P.L.E. 

290 S.W. 43rd St., Renton, WA 98055 

206/251-5222 

inCider. The Apple 11 Magazine 

80 Kim Street. Peterborough. NH 03458 

603/924-9471 

*MaeTutor: The Macintosh Programming Journal 
P.O. Box 400, Plaeentia, CA 92670 
714/630-3730 

^Nibble: The Magazine for Apple 11 Enthusiasts 
45 Wmthrop Street, Concord, MA 01742 
617/371-1660 

*Open Apple 

P.O. Box 7651, Overland Park. KS 66207 
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65816 inicropmce ssor 1-2. 13 $, 


program counter relative 33 




idd re&s spa< i 14 


program counter relative long 33 




iddressing modes .'in 


slack 33 




cycle Ume 22, 30 


stack relative 33-34 




emulation mode 1 


stack relative indirect indexed 




instruction mnemonics 50 


with Y 34 




Instruction opcodes 50 


ADSR envelope 408, 410-411 




instruction sel 22. 50 


definition 112 




native mode 1 


Alert 288-289 




iters 15 


alert boxes 267//,, 2Vs//. 




specification sheet 471 ff. 


default button 289-290 




speed 2, 13-1 1 22 


alert template 289 




8530 serial communications controller 5 


AilNotesOff 114 

AJlocGen 407-109, 415 

AL1 jOCJ NTERRU PT 39. 360-361 




A register 20 


Alternate Display Mode accessory 2, 




Abort interrupts 37, 39 


106, 311 




ABSADDR directive 47 


analog-to-digital conversion 10. 399. 407 




absolute addressing mode 35 


AND instruction 28 




absolute indexed addressing mode 35-36 


AND mask 437-438 




absolute long addressing mode 35 


API /J A 517 




access code (ProDOS) 338 


appending files 352 




> mutator 20 


Apple He 1, 13 




accumulator addressing mode 32 


Apple Me 1, 13 




activate event 123. 129. 141 


Apple lies 




active window lfil 


announcement ol 1 




ADH see Apple DeskTop Bus 


credits 12 




addition 20, 27 


Apple DeskTop Bus 7-tt, 125 




effect of earn flag 17-18 


Apple menu 247 




i Hi : 1 u| decimal mode flag I s 


Apple Programmer's Workshop 11, 12, 




address space 2. 14 


10 II 




addressing modes 


selecting a language 40 




absolute 35 


Applesoft 2. 104, 109 




absolute indexed 35-36 


Appletalk 3 




absolute loan 35 


memory usage 104 




accumulator 32 


applications, creating 49-50 




block move 34 


APW see Apple Programmer's Workshop 




direct page 35 


arithmetic Instructions 27 




direct page indexed 35-36 


ascent 197 




immediate 32 


ASCII character codes 129, 199, 463 # 




implied 30 


ASL instruction 29 




indirect 36-37 


ASML command 50 
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attributes (memory blocks) 

bank -boundary limited 113 

block 111-112 

fixed 112-113, 115 

fixed address 114-115 

fixed batik M4 

k H-ked 1 1 2 

page aligned 1 1 I 

purge level 1 13 

setting 119 

special memory not usable 113 
audio waveform 392-393 
auto-key event 129,140 
auxiliary memory 2 
auxiliary type code (Pro DOS) 341 

R register (accumulator) 20, 25 
B register (data bank) 21 
background color, text screen 9 
banks .$00 and SOI 106 
banks SE0 and $E1 102, 104-105 
baseline 197 

Brgin Update 178-180, 317 
binary-coded decimal 18 
binary-to-hex conversion 498 
BIT instruction 28 
bit-manipulation instructions 28 
block move addressing mode 34 
block move instructions 25 
block record 110. 117-118 
block-structured devices 330 
BlockMove 120-121 
blocks 110 

allocating 116-117 

disposing 1 IS- 119 

moving 120-121 

purging 118-119 
Boolean data type 75 
Bootlnit function 79 
I order color 9 
Ron rids Rett 171 
branch instructions 26 
break flag 18 
BRK instruction 18. 38, 40 
busy flag 363 
Button 128 



button (dialog) 273-274 
default 274 275 

G compiler 12 

C register 20 

GalcMenuSize 250-251 

carry flag 17-18 

Caul ion Alert 288 

CI I A N G E_ PATH 342-343 

channel address 396 

character devices 330 

character I/O 435 

character origin 197 

character rectangle 1 96- 1 97 

charactei s 

how to draw 199-201 

CharWidtb 201 
check 1k»xi j s 275 

CheckMItem 248, 2-51-252 
Choose Font 194 

Classic Desk Accessories 2. 4, 5, 70-71 
311 il 

installation 
CLEAR_BACKl P_BIT 344 
clicking 07 
clipboard 73, 244 
clock functions 144 ff 
clock speed 102, 105-106 
clock/calendar 8 
CLOSE 350 
close box 169, 176, 185 
Close Dialog 283, 285 
CloseNDAbyWinPtr 314 
Close Poly 207 
CWWindow 175. 1S2, 185 
closing files 350 
color table 163-164, 166. 273 

for a window 177 
colors: 

for patterns 188 

for pen 187 

standard 167 
comment field 42 
comment lines 41 
compaction 110-112, 115, 117 
Compact Me i ii I Id 
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comparing 

effect on carry Hag IS 

effect on flags 26 
comparison instructions 27—28 
composite video port 7 
conditional assembly 4 c i 
constant definitions 46—47 
content region 161, 168 
control characters 463 
Control M imager 72 
Control Panel accessory 2, 4, 6-7, 70- 

71, 311, 330 
cunt nils 72. 168 
COP instruction 38, 40 
COPY directive 42 
CP/M 11 

CREATE 337-338, 343 
creating files 
creation date 341 
creation time HI 3 12 
CStringWidth 201 
cursor (graphics) 14L 

mask 1-12 

record 141-142 
cursor (tenet screen) 445. 4 17 

horizontal position 447 — MS 

positioning -1 17 

vertical position 447-448 
cycle time 22 

D register 21 

data allocation directives 46 -47 

data bank register 21. 35 

data masks 437 

data types 75 

DblTiinc parameter 139 

DC directive 46 

DeallocGen ill 

DEALLOCJNTERRUPT 361 

Dec2Int 500 

Dec2Long .500 

decimal mode Hag IS 

decimal-to-binary conversion 500 

decrementing 27 

DeleteMenu 253-254 

DdtteMltem 2^1 



deleting files 

dereferencing handles 114-115 

descent 197 

desk accessories 70. 2.55. 311 ff 

and Menu Manager 248 

loading 333 
desk accessor) event 129 
Desk M imager 70 
DesfcShutDowD 312-313, 316 

startup 312-313. 3 16 
DeskTop Bus Tool Set 71 
desktop metaphor 67 
DESTROY 342 
development software 517 
device driver 436— 137 
device driver event 129 
device name 345 
diagnostics 2 
dialog boxes 267 ff, 

haw to use 283 ff. 
dialog items 271-272 
Dialog Manager 73, 267 ff. 
DialogSelecl 287-288 

DialogSluilDown 269 
DialogStartup 268-269 

I i ) eillator Chip 10. 71, 73. 389. 
392 

address register 395 

analog-to-digital register 399 

control register 395-396 

data register 395 

frequency register 395 

oscillator enable register 398-399 

oscillator interrupt register 398 

registers 394 

volume register 395 

waveform register 397-398 
direct page 14. 106 

and Pro DOS 16 14 
direct page addressing mode 35 
direct page indexed addressing 

mode 35-36 
direct page register 21 
directories 330 

directory entry 365 
Disablebltem 281 
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DisableMItem 250-251 

disabling items 280 

di.sk drives 330, 513 ff, 
3 V: inch 6 
S '-. Inch 6 

disk operating svsrera 

disk-drive port 6 

display modes 9 

DisposeAll 118-119 

DisposeHandle 111. 116, IIS 

DisposeMetiu 254 

disposing o| blocks 111 

DlgCopy 2S7 

DlgCut 287 

DlgDelcte 287 

DlgPaste 2.S7 

DOC see Digital Oscillator Chip 

DOC HAM 400 
reading 391-392 
writing .191 .492 

DOS 3.3 II 

double -click operation 139 
m ag operation 67 
Drug Window 185 
DrawChar 199, 201 
DrawCString 199-200 
drawing 186 
DrawMenuBar 249 254 
DrawString 199-200 
DmwTexl 199-200, 209 
drivers. RAM-based 136 
DS directive 46 



EA see effective address 
editable text item 277-278 
editing techniques, standard 
effective address 30 
EM Shi it Down 127 
EM Startup 126-127 
emulation flag 19 
i'ii i ulation mode I, 13 

direct page 1 I 

stack 15, 21 
EnabJeDItem 281 
Enable M Item 251 
END directive 12-13 
End Update 180, 317 
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Ensoniq ,389 
ENTRY directive 43 
EOF position 347, 354 
EOH instruction 28 
EQU directive 43 
erase operation 203 
EraseAic 204 

Ova] 204 

Poly 204 
EraseRect 204 
EraseRgn 204 
Erase R Rett 204 
error reporting, for functions B3 
ErrWriteBloek 439 
ErrWriteChar 439 
ErrWriteCstring 439 
ErrWrireLiiie 439 
ErrWrtteString 438 

event handling 136 //' 
event loop 125-126, 133-135 
Event Manager 7(1. 125 ff. 
event message 132 
event posting 135-136 
event record 130-132. 189 
event types 12S 
EventAvail 135 
events 70. L25 

activate 125 

mcmi-related 254-253 

update 12,5 
exchange instructions 25 
EXE files 50 
EXEC files 351 
expansion RAM 108-109 
expansion slots 3-4 

F FGe ne ratorS tati is 402-403 
FFSoundDoneStatus 402-403 
FFSoundS tutus 402-403 
IT Shot Sound 401. 407 
FFStopSound 402-403 
file attributes 343-344 
file level 350-351 
file system ID 345- 34(1 
file type codes 338-340 

summary 503 ff, 
filename 331 
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FILETYPE command SO, 85 

fill operation 203 
FfllArc 205 
FiltOval 205 
FttlPoly 205, 207 
Fill Red 205-2fl6 
FillRgn 205 
FillRReet 205 
filter procedure 

alerts 290 

dialogs 

SFGetFile 364-366 
FimlDItcm 281 
Find Handle 119 
FindWlndow L8&-I83 

Ideation codes 184- 1 85 
firmware RAM 10-1 
FixAppleMenu 248, .113. 317 
Fix Menu Bar 248-249, 254 
Floating-Point Numerics (SANE) 71 
flow-of-control instructions 2.5-26 
FLUSH 3.54 
FlushEvents 135 
flushing Files 354 
FM Startup 193-194 
lout 73 

attributes 198-199 

family number 194 

proportional 197 

purge status 196 

scaling 196 

selecting 194 
font characteristics 193-194 
Font Manager 73, 193-194 
font rectangle 196-197 
fontlD 194 
FORMAT 355 
formatting disks 355 
FPT see function pointer table 
frame 168 
frame operation 203 
FrameArc 204 
FrumeOval 204 
FramePoly 204, 207 
FrameRect 201 205 
Frame Rgn 204 
Frame RHect 204 



free space (unctions 121 
luc-ltjiin synthesizer 401-403 

!iii mode 396 
FrceMem 121 
frequency register, DOC 395 
Front Window 183 
full native mode, definition oi 19 
Junction pointer table 81 
functions 3 

error codes 83 

returning a result 83-83 

tool set 68 

work areas B l 

I/O port 6 
GGB .vee generator control blm-k 
GEN directive 48 
General Logic Unit (sound) 389-390 
generator 10. 392 39? 

deallocating 414 

halting 402 

priority 408-409 

status 403 
generator control block 403 
generator table 406 
GEQU directive 43 
CetBackColor 201-202 
Get Back Pat 188-189 
GetCaretTime 143 
GetCursorAdr 143 
GetDlriTimc 139 
GetDefBullon 281 
GetDltemRox 281 
GetDItemType 281 
Get D Item Value 281, 283 
GetErrGlobals 137 
Get Error Device 438 
Get Font Info 190, 197-198 
GetForeColor 201 

Get HandleS i/.e 119-120 

GetlnGlobals 437 
GetTnput Device 438 
GetlRQEnable 442 

GetlText 281-282. 285 
GetMHandle 253 
GetMItemMark 252 
GetMItemStyle 2.53 
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OtMouse 141 
GetNewPltem 271, 280, 286 
GetNVwModal Dialog 269-271. 280. 283 
GetNextEvent 182, 189, 286-287 
GetNextEvent 126, 128-133, 135-136, 

138. 140 
GetOutGIobals 437-438 
GetOutputDevice 438 

en 190 
GetPenMask 188 
GetPenPat 188 
GetPenSize 191 
GetPenState 190 L9J 
GetPort 186 
GetPorlRect 171 
GetSoundVolumc 400-401 
GetTableAddress 403-407 
GeflTextFace 199 
GetTextMode 202 
GET.BOOT.VOL 
G ET_ D E\ _ N U M 356-357 
GFT_EOF 351-453 
Gl T.FILFJNFO 343-344 
GET^LAST.DEV 357 
GET.LEVEL 351 
GF/T_MARK 353-35-1 
GET_NAME 357-358 
CET.PKEFLX 347. 358 
GET_VERSrON 358-359 
global coordinate system 132, 171-172 
global la he Is 43 
GlohalTo Local 172. 189 
GrafPort 170-173 
graphics display memory 105 
giow box 169, 176 
Grow Window 177. 185 

handle 75. 110 

dereferencing 1 14-115 
HandtoHand 120-121 
HandtoPtr 120-121 
headphone jack 5, 10 
Hertz 392 

hex-to-binary conversion 499 
Hex2tnt 498 
He\2Long 499 
Hexli 498 



HideCursor 143 
HideDItem 28] 
HideWindow 180, 182. 185 
HiliteMenu 25.5-256, 287 
HLock 112, 115. 118-119 
HLocfcAll 119 

human interface guidelines 67-68. 241. 
2.54 

HUntock 112. 115, 118-119 
HUnLockAlI 119 

I/O device 

initialization 438-439 

input 440 

logical tvpes 435-436 

output 439-440 
icon definition 279 
icon items 279 

ID numbers, for menu 244-245 
ID tag 44. N.5-116 
ImageWriter 11 437 

MouseText icons 437 
immediate addressing mode 32-33 
implied addressing mode 30 
incrementing 27 
aides register select Hag 19 
index registers 20 
indirect addressing mode 36-37 
information bar 16S. 175, 178-179 
InitGolorTable 166 
InitCursor Ml, 143 
EnitTextDev 438-439, 146 
Insert Menu 243, 248. 254 
IissrrtM r F i • 1 1 1 251 
InstallCDA 313 
Ins tall Font 196 
INSTIME directive 48 
instruction field 41 
instructions. 65816 22 
instniment, musical 409-410 
int- Dec 199 
Int2Hi\ 498 
Integer 75 

Integer Math tool set 71, 497//". 
inter-register transfer instructions 2 | 
interrupt handling 360 
and Scheduler 71 
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interrupt instructions 30 
interrupts 37 ff. 

hardware 37 

IRQ disable flap 18 

software 38 
IiitSource J 12 
InvalRect 140 
InvalRgii 140 
inverse display J 13 
invert operation 203 
InvertArc 205 
InvertOval 205 
InvertPoly 205 
InvertRect 205-206 
InvertRgn 205 
fovertRRect 205 
IRQ disable flag 18,38 
IRQ interrupts 37-39. 360 

vector 38 
IsDialogEvenl 2SB 2S7 
it* in descriptor 272-273 
it (.in ■■. alues 283 

item-definition procedure 279-280 
items 

adding to dialogs 280-281 

changing attributes 281-282 

jump instructions 26 

K register 21 

KEEP directive 42 

key-down event 129. 140 

k. j hoard 7 

keyboard equivalent 241. 247, 255 

keji board bs exits 129 

keyboard I/O 435 

ird input 441-442 
keyboard interrupts 442 
Kill Poly 207 

label field 41 
labels 

local and global (3 

naming rules 41 
language card 104 
LE Shutdown 269 
LE Startup 269 



Line 203 
line drawing 203 
LwieEdit tool set 72. 269 
LineTo 203 

and polygons 207 
LINKED language .50 
Lisa 67 

LIST directive 47 
List Manager 73, 194 
listing directives 47-48 
load file (ProDOS 16! 50 
load/store instructions 22-23 
LoadOneTool 78, BS 
LoadSysFont 196 
LoadTools 77-78, 80, 85 
local coordinates 141. 171-172 
local labels 43 
Loea IToG iobal 1 72 
locking blocks 115. 118 
logical instructions 28 
long integer 75 
long static text items 276—277 
Lou g2 Dec 500 
Long2Hex 498 
LONCA directive 44 
LONG! directive 44 
LSR instruction 29 

m flag 19 

MACGEN program 49. 75 

Macintosh XL 67 

macro definitions 48-49, 68 

macro files 

APW 76 

too! sets 495 
magazines 521 
main memory 2 
mark position 347, 352, 354 
master pointer 110 

removal 118 
MaxBlock 121 
MCOPY directive 42, 49 
measuring text 201 
memory bank, definition of 14 
memory expansion 102 
memory expansion cards 109. 507 ff. 
memory expansion slot 3 
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Memory Manager 68, 102. HOjfjf. 

available memory 106 
memory map 102-103 
memory space 101 
memory usage 2 

memory /accumulator select flag 19 
menu 241 

color 256 

creating 243 

removing 253 
menu bar 241 

creating 248 

size 249 
menu item 

appearance 24fH 

changing attributes 249 

changing name 249-250 

checking 251-252 

Close item 244 

color-replace highlighting 247 

deleting 251 

desk accessory item 244 

disabling 24(1 250-251 

dividing line : 

editing 244 

enabling 250-251 

inserting 251 

marking 248, 251-252 

text style 252-253 
Menu Manager 72, 241 
menu title-' 

changing name 249 

highlighting 255-256 
menu/item line list 243-244 
MenuKey 255 
Menu Select 254-255 
Menu Shutdown 243 
MenuStartup 242 
MIDI 409, 413 
mini-assenililer 2 
Miscellaneous Tool Set 70, 144 
MMShutUown 116 
M MS),,, tup 115 117., 126 
modal dialog boxes 269-271 
ModalDiabg 270. 2S3-2S5, 288-289 
modeless dialog boxes 269, 28 
modification tune 344 



modifier Bags 1,32-133 

modifier keys 129 

most-significant bit 18 

mouse 8 

mouse activity, in windows \H3ff. 

-.r events 12S 

mouse-down 128, 138 

mouse-up 128, 139 
MouscText 443, 4 15 
Move 189, 190, 199-200 
MoveTo 189. 190, 198-200 
MTShutDowu 144 
MTStartup 144 
MVN instruction 25, 34 
MVP instruction 25, 24 



native mode 1, 13, 44 

negative flag 19 

negative numbers 19 

New Desk Accessories To, 311 ff. 

installation 317 
New-Video register 162 
NewBarColor 256 
NewDItem 27 1 , 280-281 , 286 
NcwHandle 110-111, 114, 116-118, 127 
NewlnvertColor 2.56 
NEWLINE 349 
newliue character 349 
NewMenn 243 248, 253-254 
NewModalBialog 269-271, 280, 283 
New ModelessDtalog 285-286 
NewOutColor 256 
New Window 140, 170, 173, 175-176, 

179-180, 182, 208-209 
NMI interrupts 37, 39 
NOP instruction 30 
Note Sequencer 73 
Note Synthesizer 73, 407-408 
NotcAlrrt 288 
NnteOir 407, 112, 414 11" 
NotcUn 4(17, 409, 415 
NSShutDown 414 
NSStarlnp 408. 412-113, 415 
NTSC video port 7 

number conversion 497 jfjf 
numbering systems 44—15 
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OBJ files 42 
object code t< intuit 50 
Obscui eCu rm »r I 13 
Offset Poly 207 
one-shot mode 397 
opcode 22 
OPEN 348 
opening files 348 
OpenNDA 314 
Open Poly 207 
operand 22 
operand field 42 
operating systems 10-11 
OR mask 437-438 
ORA instruction 28 
oscillator mode 397. 413 
oscillator, halting 393 
overflow flag IS- 19 

page region 169 

paint operation 203 

PaintArc 204 

PaintOval 204 

PaintPoly 204, 207 

PamtRect 204, 206 

PaintRgn 204 

PaintRKect 2<I4 

palette f 63-164. 166. 170-171 

ParamText 277, 282 

partial pathname 332 

Pascal 1 1 

pathname ."131 

pattern 187-189 

background 1S9 

mask 187 
PC register 21-22 
PEA instruction 23 
PE1 instruction 23 
pen 186 

characteristics 186 
pen modes 191-193 
pen position 189-190 
pen size 191 
pen state 190-191 

how to change 191 
PenNormal 191 
PER instruction 23 



peripheral ROM 104-105 
phantom slots 3 
picture i ten is 27 9 
pitch 392 
pltehbend 408, 412 

point, definition ol 187 

pointer 75 

polygons 207-208 

Pop Long macro 76—7 

Pop Word macro 76-77 

Portlnfb field 170 

PortRecl field 1 7 1 

ports I 

PostEvent 135-136 

prefixes 332-333. 346 

PRINT macro 440 

Print Manager 72 

printer commands 449 

printer I/O 435 

printer output 437, 449 

PRINTLN macro 440 

processor status register 16-17 

PraDOS 16 11, 72, 329 ff. 

boot disk structure 332 

commands 334, 336 

entry conditions 43—44 

errors 334 

memory usage 102. 104 
Pro DOS 8 11, 329 

memory usage 101 
Pro DOS. and t lie clock 8 
program bank register 21, 35 
program counter 21-22 

bank wrapping 22 
program counter relative addressing 

mode 33 
program counter relative long addressing 

made 33 
PtrtoHand 120-121 
pull instructions 24 
pull-down menu 241-242 
purge level 110-113 

setting 119 
PurgeAll 119 
Purge Han die 113, 119 
purging 113, 117, 118 
push instructions 23 
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PushLong macro 76 
PushPtr macro 76 
Push Word macro 76 

QDAuxShutDown 111 

QD A ux Startup 143 

QDShulDown 162 

QDStartup 162, 172 

Ouiekdraw Auxiliary Tool Set 72. 143 

QuickDraw I] 70, 162$ 

QUIT 50. 359-360 

Quit Return Stack 359-360 

radio buttons 275 
HAM disk 330 

booting from 6-7 

how to use fi 
RAM Disk Tool Set 71 
RAM expansion 102 
READ 349-350 
HeadA.sciiTime 144 
ReadChar 440—141 

reading files 348, .350 

ReadLine 440-441 

ReadRanriBlnck 400 

ReadTimeHex 85. 144-145 

READ. BLOCK .356 

Real lot Handle 110-111, 113-114, lib 

rectangle, definition of 187 

reference books 518 

Refresh Desktop 173 

register select flags 19 

registers 15 

renaming files 342-343 

REP instruction 19-20 H 

reply record 363-364, 367 

Reset function 79 

Reset interrupts 37. 39 

RestoreHaridle 110, 113-114 IIS 

return address 26' 

RGB video port 7 

ROL instruction 29 

ROM disk 7, 110 

ROM expansion 102. 110 

ROM space 2 

root directory 330 



ROR instruction 29 

RTI instruction 38-39 

S16 files 50 

sampling rate 395 

SANE 71 

seanline control byte 163-164, 167 

SCB see seanline control byte 

SCC nee 8530 serial communications 
controller 

SchAddTask 361 

Scheduler 71. 381 

Scrap Manager 73 

scroll arrow 169 

scroll bats 169. 175-176, 17S. 275-276 

selecting a filename 362 

Select Window 181-185 

SellTe.vt 281-282 

semitone 408 

SEP instruction 19-20. 44 

serial ports 5, 449 

SetAllSCBs 187 

SetBackCoIor 197. 201 

SetBackPat 188 -188, 203 

SetBarColors 256 

SetColorEntry 166 

SetColorTable 167 

Set Content Draw 181 
SetContentOrigin 181 
SetCursor 141. 143 
SetDataSize IS I 
SetDefButton 281 
SetDefProc 181 
SetDltemBox 281 
SelDltemType 281 
SetDItem Value 281, 283 
SetErrGlobals 437 
SetError Device 438 
SetFontFlags 197 
SefForcColor 197, 201-202 
SetFrarneColor 181 
Set Full Rect 181 
SetHandleSize 120 
SetlnfoDraw IS I 
SetlnroRefCon 18] 
SetlnClobals 437 
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Set Input Device 438 
St 11 Text 281-282 
SetMaxCrow 181 
SetMenuTide 249 
SelMltem 219, 251 
Set Ml tern Mark 252 
SetMItetnName 249-250 
SetMIteraStyle 252 
SetOrigm 171- 177. 180,209 
SerOulGlobals 137 
SetOutpui Device 438 
SetPage 181 
SetFenMask LS8, 191 
SctPenMode 191 
SelPenPal 188, 191, 203 
SetPenSize 191 
SetPenState 191 
SctPort 186 
SetPnrge 113. 119 
Set Purge-All 119 
SetPuigeStat 196 
SetSCB 167 
Set Sera II 181 
SetSolidBackPat 188-189. 20.3 

SetSolidPenFat 188-189. 203 
SetSoundMIRQY 402 

SetSoundVolume 400-401 

SerTextFace 194. 198 

SetTextMode 202 

SetTSPtr 81, SI 

Setl serSouodlRQV 

SetWAP 84, 127 

SetWFrame IS1 

SetWHeECon 181 

SetWTitle 181 

SET_EOF 347. 353-354 

5ET~FILE_INFO 342-344 

SET_ LEVEL 350^-351 

SET.MARK 347-350 

SET_PREF1\ 332, 346 

SFGetFile 362-365, 367-369 

SFShutPuwn 

SFStartup 362 

shadow register 106 

shadowing 106— 108 

shape drawing 203 



-Jul! and rotate 18 
instructions 29 
ShowC.urs.or 143 
ShowDItem 281 
ShowWindW 140, 173. 175. 180 
Shut Down Function 79—80 
SizeWindow 185 
Slots command 5 
soil switches 3. 104 
software interrupts 40 
SolidPatteni 188-189 
SONG program 414 U5 

sound 10 

output 393 

output channels 393-394 
Sound Control register 390-391 
Sound GLU 10 
Sound Manager 7 L 399 ff. 
SoundShutDown 399 
SoundStartup 399, 403, 406, 408 
source code format 41 

comment field 42 

comment lines' 41 

instruction Held 41 

label field 41 

operand Seld 42 
SP register L5, 21, 23 
speaker 5, 10. 389, 392 
special characters (menu) 244-243 
speed 2, 13-14. 22 
SRC files 341 
stack 14-15 T 21, 106 

ProDOS 16 44 

pulling 15 

pushing 15 

stack pointer 15, 21. 23 
stuck addressing mode 33 
stack pointer 15, 21, 23 
stack relative addressing mode 33-34 B2 
stack relative indirect indexed with Y 

addressing mode 34 
stage bytes 289 
Standard File Operations Tool Set 73. 

362 
STANDARD. ASM program 79-80, IS,. 

269. 272 
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START directive 42-43 
START program 333-334. 360 
StartDrawing 177, 180, 186 
Startup function 79-80 
static text items 276-277 
status flags 16-J7 
Status function 79 
status register tee processor status 

register 

StillDown 140 

StopAlert 288 

storage type code (ProPOS) 341 

STR macro 200 

string printing 440 

StringWidth 201 

style word 253 

subdirectory 330 

subroutines 26 

subtraction 20, 27 

effec t of earn' flag 17-18 
effect of decimal mode flag 18 
super hires graphics 162-167 
colors 9 

genera] description 9 
memory usage 105 
swap mode 397 
switch event 129 
SYMBOL directive 47 
sync mode 397 
Sv.sBeep 389 
system font 196, 463 

height 190 
System Loader 72 

men inn' usage 104 
purge level 113 
System Monitor 2, 101, 109 
system window 312 
system-control instructions 29-30 
SystemClkk 314 
System Edit 314 
SystemTask 314 

Table Size 397-398 

TaskMaster 131, 136, 138. 173, 176-179, 
L82-186. 189 208, 210, 255, 269, 286-' 

2S7 



text color 201-202 

text display memory 105 
text items 

reading values 281-282 
selecting a range 282 
Text Tool Set 71, 435 # 
text transfer modes 202 
TextRead Block 440-441 
TextRead ei program 179. 208-210 
TextShutDown 435 
TextStartup 435 
TcxtWidth 201 
TextWriteBlock 439-440 
thumb 169 
TickCount 145-146 
ticks 132. 145-146 
time formats 144 
TimeTool.s 84-85 
title bar 168-169. 176 
TlAknmt Volume 7S-7 f J 
TLShutDown 77 

effect on RAM -based tools 78 
effect on user TFT 85 
TLStartup 77. 126 

effect on user TPT 85 
Tool locator 68,77// 
tool pointer table 81 
boa] sets 67-68 
errors 74 

general description 3 
how to use 73-75 
in ROM 3 
loading them 77-78 
structure 79 
sum man' 68, 495 ff. 
user-defined 84-85 
writ in k your owi i 80 ff. 
TOOL.SETUP program 332. 485 
Inf., I Mem 121 
TFT see tool pointer table 
TrackGoAway 185 
TrackZtMim 185 
TRB instruction 28-29 
TSB instruction 28-29 
two's-complement numbers 18-19 
TypeList 366-367 
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Undo 2S7 

InloadOneTonl 78 

unlocking US 

update event 125, 129, L40-14J 

updating windows 178-180 

user control items 276 

user items 279 

USING directive 43 

Version function 79 

version number (ProDOS 16) 3.58-359 

for prototypes 79 
vibrato 408. 413 
video buffer 162 
video I/O 435 
video output 44 3 
video HAM 105 
voices 10, 392 

VOLUME (ProDOS) 345 355-356 
volume (Pro IX >S: 330 

characteristics 345 

director) 330-331 
volume (audio] 4oo -40| 

control 390-3&1 

WaitGunor 143 

Wait Mouse Up 140 

WAIT see Work Ana Pointer Table 

waveform 392r4J93 395 397,402 

form resolution 398 
WDM instruction 30 
widMax 197 



Window Manager 72. IGlff. 
window 161. 168 j(]F, 

changing properties 180 

creating L73 

events 1 29 

moose activity in 183 [i 

record 1 70 

removing 182 

text screen 4 IS- 449 

title 177 
WindShutDuwn 173 
WindStartup 173 

Work Area Pointer Table 68, 79. B4, 127 
WRITE 351 
WriteChar 439 
WriteCString 439-440 
WritoLine 439-140 
WriteRamBloek 400, 407 
WriteString 439-440 
WRITE.BLOCK 356 
writing files 351-352 

x Hag 19-20 

\ regjstei 20 

XBA instruction 20, 25 

XCE instruction 19 f 25 

Y register 20 

Avtu Hag IS 

zoon) box 168, 175, 177, 185 

Zoom Window 185 
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Program Disk for 

Exploring the Apple IlGS 
by Gary B. Little 



All of the programs listed in this book are available on disk, in source code form, 
directly from the author. The disk also contains several other programs, including some 
useful desk accessories and a program to display and print screen image files. 

TO ORDER the disk, simply clip or photocopy this entire page and complete the 
coupon below. Enclose a check or money order for $20.00 in U.S. funds. (California 
residents add applicable state sales tax.) 



MAIL TO: GARY B, LITTLE 

1925 Bayview Avenue 
Belmont, CA 94002 



Please send me: 

(quantity) Disks to accompany Exploring the Apple lies, by Gary B, Little, at 

$20.00 each. 



Check enclosed. 



YOUR SIGNATURE; 



Name: Title: 

Company (if applicable): 

Address: , 



City: State: Zip: 



GARY B. UTTLE 



tt Addison-Wesley Publishing Company 



EXPLORING 
THE APPLE IIgs 

Best-selling author Gary B. Little reveals the 
power of the amazing new Apple IIgs 

The Apple Hgs "is the sophisticated new member of the Apple" II family of 
computers with outstanding color graphics and sound capabilities. It features 
a powerful 16-bit, 65816 microprocessor, custom sound and graphics chips, an 
enhanced operating system called ProDOS 16, and a Macintosh -like Toolbox 
of programming toots to help programmers easily create windows, pull -down 
menus, dialog boxes, and other user interface components. 

Now Gary B. Little, the author of the acclaimed Inside the Apple lie and Inside 
the Apple Ik has written an in-depth, technical introduction to the inner work- 
ings of the Apple IIgs. Written for all assembly language and Applesoft BASIC pro- 
grammers. Exploring the Apple IIgs is a detailed study of how the Apple IIgs is 
built and how it works. 

Little provides thorough discussions of: 

• the architecture and capabilities of the 65816 microprocessor 

• software development environments and utilities 

• the Apple IIgs Programmers Workshop 

• file management with ProDOS 16 

• memory map and memory management 

• using Super Hi-Res graphics 

• event handling 

• using the Apple IIgs Toolbox 

Little's easy-to-read style makes the intricacies of programming the Apple IIgs 
readily accessible. He analyzes all the major functions a programmer will have to 
know and shows how to assemble them into a complete application. Each chapter 
features extensive examples of program code. Exploring the Apple IIgs is the 
ideal guide to learning to program ,the exciting Apple IIgs. 

Gary B. Little is a well-known author, columnist and software developer. He is a 
leading authority on the Apple II family of computers. His books include the best- 
selling Inside the Apple He, Inside the Apple lie, and Apple ProDOS: Advanced 
Features for Programmers. Gary is the developer of the Point-to- Point commu- 
nications program and he is also a Contributing Editor for A + Magazine. He prac- 
tices computer law in Vancouver, British Columbia. 

Cover design by Doliber Skeff ington 



